@effect/platform 0.66.2 → 0.66.3

package/src/Headers.ts

@@ -117,10 +117,26 @@ export const unsafeFromRecord = (input: Record.ReadonlyRecord<string, string>):
  * @category combinators
  */
 export const has: {
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string): (self: Headers) => boolean
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string): boolean
 } = dual<
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string) => (self: Headers) => boolean,
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string) => boolean
 >(2, (self, key) => key.toLowerCase() in self)
 
@@ -129,10 +145,26 @@ export const has: {
  * @category combinators
  */
 export const get: {
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string): (self: Headers) => Option.Option<string>
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string): Option.Option<string>
 } = dual<
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string) => (self: Headers) => Option.Option<string>,
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string) => Option.Option<string>
 >(2, (self, key) => Record.get(self as Record<string, string>, key.toLowerCase()))
 
@@ -141,10 +173,26 @@ export const get: {
  * @category combinators
  */
 export const set: {
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string, value: string): (self: Headers) => Headers
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string, value: string): Headers
 } = dual<
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string, value: string) => (self: Headers) => Headers,
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string, value: string) => Headers
 >(3, (self, key, value) => {
   const out = make(self)
@@ -157,10 +205,26 @@ export const set: {
  * @category combinators
  */
 export const setAll: {
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (headers: Input): (self: Headers) => Headers
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, headers: Input): Headers
 } = dual<
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (headers: Input) => (self: Headers) => Headers,
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, headers: Input) => Headers
 >(2, (self, headers) =>
   make({
@@ -173,10 +237,26 @@ export const setAll: {
  * @category combinators
  */
 export const merge: {
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (headers: Headers): (self: Headers) => Headers
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, headers: Headers): Headers
 } = dual<
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (headers: Headers) => (self: Headers) => Headers,
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, headers: Headers) => Headers
 >(2, (self, headers) => {
   const out = make(self)
@@ -189,10 +269,26 @@ export const merge: {
  * @category combinators
  */
 export const remove: {
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string): (self: Headers) => Headers
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string): Headers
 } = dual<
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (key: string) => (self: Headers) => Headers,
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
   (self: Headers, key: string) => Headers
 >(2, (self, key) => {
   const out = make(self)
@@ -205,13 +301,16 @@ export const remove: {
  * @category combinators
  */
 export const redact: {
-  (
-    key: string | RegExp | ReadonlyArray<string | RegExp>
-  ): (self: Headers) => Record<string, string | Redacted.Redacted>
-  (
-    self: Headers,
-    key: string | RegExp | ReadonlyArray<string | RegExp>
-  ): Record<string, string | Redacted.Redacted>
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
+  (key: string | RegExp | ReadonlyArray<string | RegExp>): (self: Headers) => Record<string, string | Redacted.Redacted>
+  /**
+   * @since 1.0.0
+   * @category combinators
+   */
+  (self: Headers, key: string | RegExp | ReadonlyArray<string | RegExp>): Record<string, string | Redacted.Redacted>
 } = dual(
   2,
   (

package/src/HttpApi.ts

@@ -134,21 +134,45 @@ export const empty: HttpApi = makeProto({
  * @category constructors
  */
 export const addGroup: {
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Group extends HttpApiGroup.HttpApiGroup.Any>(
     group: Group
   ): <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR>(
     self: HttpApi<Groups, Error, ErrorR>
   ) => HttpApi<Groups | Group, Error, ErrorR>
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Group extends HttpApiGroup.HttpApiGroup.Any>(
     path: HttpRouter.PathInput,
     group: Group
   ): <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR>(
     self: HttpApi<Groups, Error, ErrorR>
   ) => HttpApi<Groups | Group, Error, ErrorR>
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, Group extends HttpApiGroup.HttpApiGroup.Any>(
     self: HttpApi<Groups, Error, ErrorR>,
     group: Group
   ): HttpApi<Groups | Group, Error, ErrorR>
+  /**
+   * Add a `HttpApiGroup` to an `HttpApi`.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, Group extends HttpApiGroup.HttpApiGroup.Any>(
     self: HttpApi<Groups, Error, ErrorR>,
     path: HttpRouter.PathInput,
@@ -178,6 +202,15 @@ export const addGroup: {
  * @category errors
  */
 export const addError: {
+  /**
+   * Add an error schema to an `HttpApi`, which is shared by all endpoints in the
+   * `HttpApi`.
+   *
+   * Useful for adding error types from middleware or other shared error types.
+   *
+   * @since 1.0.0
+   * @category errors
+   */
   <A, I, R>(
     schema: Schema.Schema<A, I, R>,
     annotations?: {
@@ -186,6 +219,15 @@ export const addError: {
   ): <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR>(
     self: HttpApi<Groups, Error, ErrorR>
   ) => HttpApi<Groups, Error | A, ErrorR | R>
+  /**
+   * Add an error schema to an `HttpApi`, which is shared by all endpoints in the
+   * `HttpApi`.
+   *
+   * Useful for adding error types from middleware or other shared error types.
+   *
+   * @since 1.0.0
+   * @category errors
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, A, I, R>(
     self: HttpApi<Groups, Error, ErrorR>,
     schema: Schema.Schema<A, I, R>,
@@ -219,7 +261,15 @@ export const addError: {
  * @category annotations
  */
 export const annotateMerge: {
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <I>(context: Context.Context<I>): <A extends HttpApi.Any>(self: A) => A
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApi.Any, I>(self: A, context: Context.Context<I>): A
 } = dual(
   2,
@@ -236,7 +286,15 @@ export const annotateMerge: {
  * @category annotations
  */
 export const annotate: {
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApi.Any>(self: A) => A
+  /**
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApi.Any, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
 } = dual(
   3,

package/src/HttpApiBuilder.ts

@@ -57,10 +57,28 @@ export class Router extends HttpRouter.Tag("@effect/platform/HttpApiBuilder/Rout
  * @category constructors
  */
 export const serve: {
+  /**
+   * Build an `HttpApp` from an `HttpApi` instance, and serve it using an
+   * `HttpServer`.
+   *
+   * Optionally, you can provide a middleware function that will be applied to
+   * the `HttpApp` before serving.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
   (): Layer.Layer<never, never, HttpServer.HttpServer | HttpApi.HttpApi.Service | HttpRouter.HttpRouter.DefaultServices>
-  <R>(
-    middleware: (httpApp: HttpApp.Default) => HttpApp.Default<never, R>
-  ): Layer.Layer<
+  /**
+   * Build an `HttpApp` from an `HttpApi` instance, and serve it using an
+   * `HttpServer`.
+   *
+   * Optionally, you can provide a middleware function that will be applied to
+   * the `HttpApp` before serving.
+   *
+   * @since 1.0.0
+   * @category constructors
+   */
+  <R>(middleware: (httpApp: HttpApp.Default) => HttpApp.Default<never, R>): Layer.Layer<
     never,
     never,
     | HttpServer.HttpServer
@@ -313,6 +331,12 @@ export const group = <
  * @category handlers
  */
 export const handle: {
+  /**
+   * Add the implementation for an `HttpApiEndpoint` to a `Handlers` group.
+   *
+   * @since 1.0.0
+   * @category handlers
+   */
   <Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, const Name extends Endpoints["name"], E, R>(
     name: Name,
     handler: HttpApiEndpoint.HttpApiEndpoint.HandlerWithName<Endpoints, Name, E, R>
@@ -321,6 +345,12 @@ export const handle: {
     RG | HttpApiEndpoint.HttpApiEndpoint.ExcludeProvided<R>,
     HttpApiEndpoint.HttpApiEndpoint.ExcludeName<Endpoints, Name>
   >
+  /**
+   * Add the implementation for an `HttpApiEndpoint` to a `Handlers` group.
+   *
+   * @since 1.0.0
+   * @category handlers
+   */
   <Endpoints extends HttpApiEndpoint.HttpApiEndpoint.All, const Name extends Endpoints["name"], E, R>(
     name: Name,
     handler: HttpApiEndpoint.HttpApiEndpoint.HandlerResponseWithName<Endpoints, Name, E, R>,
@@ -436,18 +466,36 @@ const middlewareAddNoContext = (
  * @category middleware
  */
 export const middlewareLayer: {
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <EX = never, RX = never>(
     middleware: ApiMiddleware.Fn<never> | Effect.Effect<ApiMiddleware.Fn<never>, EX, RX>,
     options?: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, RX>
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <R, EX = never, RX = never>(
     middleware: ApiMiddleware.Fn<never, R> | Effect.Effect<ApiMiddleware.Fn<never, R>, EX, RX>,
     options: {
       readonly withContext: true
     }
   ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | RX>
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, EX = never, RX = never>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: ApiMiddleware.Fn<NoInfer<Error>> | Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>>, EX, RX>,
@@ -455,6 +503,12 @@ export const middlewareLayer: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, RX>
+  /**
+   * Create an `HttpApi` level middleware `Layer`.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, R, EX = never, RX = never>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: ApiMiddleware.Fn<NoInfer<Error>, R> | Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>, R>, EX, RX>,
@@ -493,18 +547,39 @@ export const middlewareLayer: {
  * @category middleware
  */
 export const middlewareLayerScoped: {
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <EX, RX>(
     middleware: Effect.Effect<ApiMiddleware.Fn<never>, EX, RX>,
     options?: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, Exclude<RX, Scope>>
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <R, EX, RX>(
     middleware: Effect.Effect<ApiMiddleware.Fn<never, R>, EX, RX>,
     options: {
       readonly withContext: true
     }
   ): Layer.Layer<never, EX, HttpRouter.HttpRouter.ExcludeProvided<R> | Exclude<RX, Scope>>
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, EX, RX>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>>, EX, RX>,
@@ -512,6 +587,13 @@ export const middlewareLayerScoped: {
       readonly withContext?: false | undefined
     }
   ): Layer.Layer<never, EX, Exclude<RX, Scope>>
+  /**
+   * Create an `HttpApi` level middleware `Layer`, that has a `Scope` provided to
+   * the constructor.
+   *
+   * @since 1.0.0
+   * @category middleware
+   */
   <Groups extends HttpApiGroup.HttpApiGroup.Any, Error, ErrorR, R, EX, RX>(
     api: HttpApi.HttpApi<Groups, Error, ErrorR>,
     middleware: Effect.Effect<ApiMiddleware.Fn<NoInfer<Error>, R>, EX, RX>,

package/src/HttpApiEndpoint.ts

@@ -444,6 +444,13 @@ export const del: <const Name extends string>(
  * @category result
  */
 export const setSuccess: {
+  /**
+   * Set the schema for the success response of the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 200.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <S extends Schema.Schema.Any>(
     schema: S,
     annotations?: {
@@ -461,6 +468,13 @@ export const setSuccess: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, _P, _H, Schema.Schema.Type<S>, _E, _R | Schema.Schema.Context<S>>
+  /**
+   * Set the schema for the success response of the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 200.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -513,6 +527,13 @@ export const setSuccess: {
  * @category result
  */
 export const addError: {
+  /**
+   * Add an error response schema to the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 500.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <E extends Schema.Schema.All>(
     schema: E,
     annotations?: {
@@ -530,6 +551,13 @@ export const addError: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E | Schema.Schema.Type<E>, _R | Schema.Schema.Context<E>>
+  /**
+   * Add an error response schema to the endpoint. The status code
+   * will be inferred from the schema, otherwise it will default to 500.
+   *
+   * @since 1.0.0
+   * @category result
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -593,9 +621,20 @@ export const addError: {
  * @category request
  */
 export const setPayload: {
-  <Method extends HttpMethod, P extends Schema.Schema.All>(
-    schema: P & HttpApiEndpoint.ValidatePayload<Method, P>
-  ): <
+  /**
+   * Set the schema for the request body of the endpoint. The schema will be
+   * used to validate the request body before the handler is called.
+   *
+   * For endpoints with no request body, the payload will use the url search
+   * parameters.
+   *
+   * You can set a multipart schema to handle file uploads by using the
+   * `HttpApiSchema.Multipart` combinator.
+   *
+   * @since 1.0.0
+   * @category request
+   */
+  <Method extends HttpMethod, P extends Schema.Schema.All>(schema: P & HttpApiEndpoint.ValidatePayload<Method, P>): <
     Name extends string,
     _Path,
     _P,
@@ -606,6 +645,19 @@ export const setPayload: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, Schema.Schema.Type<P>, _H, _S, _E, _R | Schema.Schema.Context<P>>
+  /**
+   * Set the schema for the request body of the endpoint. The schema will be
+   * used to validate the request body before the handler is called.
+   *
+   * For endpoints with no request body, the payload will use the url search
+   * parameters.
+   *
+   * You can set a multipart schema to handle file uploads by using the
+   * `HttpApiSchema.Multipart` combinator.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -650,9 +702,14 @@ export const setPayload: {
  * @category request
  */
 export const setPath: {
-  <Path extends Schema.Schema.Any>(
-    schema: Path & HttpApiEndpoint.ValidatePath<Path>
-  ): <
+  /**
+   * Set the schema for the path parameters of the endpoint. The schema will be
+   * used to validate the path parameters before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
+  <Path extends Schema.Schema.Any>(schema: Path & HttpApiEndpoint.ValidatePath<Path>): <
     Name extends string,
     Method extends HttpMethod,
     _Path,
@@ -664,6 +721,13 @@ export const setPath: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, Schema.Schema.Type<Path>, _P, _H, _S, _E, _R | Schema.Schema.Context<Path>>
+  /**
+   * Set the schema for the path parameters of the endpoint. The schema will be
+   * used to validate the path parameters before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -708,9 +772,14 @@ export const setPath: {
  * @category request
  */
 export const setHeaders: {
-  <Method extends HttpMethod, H extends Schema.Schema.Any>(
-    schema: H & HttpApiEndpoint.ValidateHeaders<H>
-  ): <
+  /**
+   * Set the schema for the headers of the endpoint. The schema will be
+   * used to validate the headers before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
+  <Method extends HttpMethod, H extends Schema.Schema.Any>(schema: H & HttpApiEndpoint.ValidateHeaders<H>): <
     Name extends string,
     _Path,
     _P,
@@ -721,6 +790,13 @@ export const setHeaders: {
   >(
     self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
   ) => HttpApiEndpoint<Name, Method, _Path, _P, Schema.Schema.Type<H>, _S, _E, _R | Schema.Schema.Context<H>>
+  /**
+   * Set the schema for the headers of the endpoint. The schema will be
+   * used to validate the headers before the handler is called.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <
     Name extends string,
     Method extends HttpMethod,
@@ -764,7 +840,19 @@ export const setHeaders: {
  * @category request
  */
 export const prefix: {
+  /**
+   * Add a prefix to the path of the endpoint.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   (prefix: HttpRouter.PathInput): <A extends HttpApiEndpoint.All>(self: A) => A
+  /**
+   * Add a prefix to the path of the endpoint.
+   *
+   * @since 1.0.0
+   * @category request
+   */
   <A extends HttpApiEndpoint.All>(self: A, prefix: HttpRouter.PathInput): A
 } = dual(2, <A extends HttpApiEndpoint.All>(self: A, prefix: HttpRouter.PathInput): A =>
   makeProto({
@@ -788,7 +876,19 @@ export const schemaSuccess = <A extends HttpApiEndpoint.All>(
  * @category annotations
  */
 export const annotateMerge: {
+  /**
+   * Merge the annotations of the endpoint with the provided context.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I>(context: Context.Context<I>): <A extends HttpApiEndpoint.All>(self: A) => A
+  /**
+   * Merge the annotations of the endpoint with the provided context.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiEndpoint.All, I>(self: A, context: Context.Context<I>): A
 } = dual(
   2,
@@ -806,7 +906,19 @@ export const annotateMerge: {
  * @category annotations
  */
 export const annotate: {
+  /**
+   * Add an annotation to the endpoint.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApiEndpoint.All>(self: A) => A
+  /**
+   * Add an annotation to the endpoint.
+   *
+   * @since 1.0.0
+   * @category annotations
+   */
   <A extends HttpApiEndpoint.All, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
 } = dual(
   3,