effect 4.0.0-beta.4 → 4.0.0-beta.41

package/src/unstable/httpapi/HttpApiClient.ts

@@ -8,7 +8,7 @@ import { identity } from "../../Function.ts"
 import * as Option from "../../Option.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Schema from "../../Schema.ts"
-import type * as AST from "../../SchemaAST.ts"
+import * as AST from "../../SchemaAST.ts"
 import * as Issue from "../../SchemaIssue.ts"
 import * as Transformation from "../../SchemaTransformation.ts"
 import type * as ServiceMap from "../../ServiceMap.ts"
@@ -23,7 +23,7 @@ import * as HttpMethod from "../http/HttpMethod.ts"
 import * as UrlParams from "../http/UrlParams.ts"
 import * as HttpApi from "./HttpApi.ts"
 import * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
-import type { HttpApiSchemaError } from "./HttpApiError.ts"
+import type { BadRequest } from "./HttpApiError.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import type * as HttpApiMiddleware from "./HttpApiMiddleware.ts"
 import * as HttpApiSchema from "./HttpApiSchema.ts"
@@ -32,7 +32,7 @@ import * as HttpApiSchema from "./HttpApiSchema.ts"
  * @since 4.0.0
  * @category models
  */
-export type Client<Groups extends HttpApiGroup.Any, E, R> = Simplify<
+export type Client<Groups extends HttpApiGroup.Any, E = BadRequest, R = never> = Simplify<
   & {
     readonly [Group in Extract<Groups, { readonly topLevel: false }> as HttpApiGroup.Name<Group>]: Client.Group<
       Group,
@@ -46,11 +46,34 @@ export type Client<Groups extends HttpApiGroup.Any, E, R> = Simplify<
   }
 >
 
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export type ForApi<Api extends HttpApi.Any, E = BadRequest, R = never> = Api extends
+  HttpApi.HttpApi<infer _Id, infer Groups> ? Client<Groups, E, R> :
+  never
+
 /**
  * @since 4.0.0
  * @category models
  */
 export declare namespace Client {
+  /**
+   * @since 4.0.0
+   * @category models
+   */
+  export type ResponseMode = HttpApiEndpoint.ClientResponseMode
+
+  /**
+   * @since 4.0.0
+   * @category models
+   */
+  export type Response<Success, Mode extends ResponseMode> = [Mode] extends ["decoded-and-response"]
+    ? [Success, HttpClientResponse.HttpClientResponse]
+    : [Mode] extends ["response-only"] ? HttpClientResponse.HttpClientResponse
+    : Success
+
   /**
    * @since 4.0.0
    * @category models
@@ -80,23 +103,21 @@ export declare namespace Client {
       infer _Middleware,
       infer _MR
     >
-  ] ? <WithResponse extends boolean = false>(
-      request: Simplify<HttpApiEndpoint.ClientRequest<_Params, _Query, _Payload, _Headers, WithResponse>>
+  ] ? <Mode extends ResponseMode = ResponseMode>(
+      request: Simplify<HttpApiEndpoint.ClientRequest<_Params, _Query, _Payload, _Headers, Mode>>
     ) => Effect.Effect<
-      WithResponse extends true ? [_Success["Type"], HttpClientResponse.HttpClientResponse] : _Success["Type"],
-      | _Error["Type"]
+      Response<_Success["Type"], Mode>,
       | HttpApiMiddleware.Error<_Middleware>
       | HttpApiMiddleware.ClientError<_Middleware>
       | E
       | HttpClientError.HttpClientError
-      | Schema.SchemaError,
+      | ([Mode] extends ["response-only"] ? never : _Error["Type"] | Schema.SchemaError),
       | R
       | _Params["EncodingServices"]
       | _Query["EncodingServices"]
       | _Payload["EncodingServices"]
       | _Headers["EncodingServices"]
-      | _Success["DecodingServices"]
-      | _Error["DecodingServices"]
+      | ([Mode] extends ["response-only"] ? never : _Success["DecodingServices"] | _Error["DecodingServices"])
     > :
     never
 
@@ -112,6 +133,49 @@ export declare namespace Client {
       never
 }
 
+type UrlBuilderRequest<Endpoint extends HttpApiEndpoint.Any> = (
+  & ([HttpApiEndpoint.Params<Endpoint>["Type"]] extends [never] ? {}
+    : { readonly params: HttpApiEndpoint.Params<Endpoint>["Type"] })
+  & ([HttpApiEndpoint.Query<Endpoint>["Type"]] extends [never] ? {}
+    : { readonly query: HttpApiEndpoint.Query<Endpoint>["Type"] })
+) extends infer Request ? keyof Request extends never ? void | undefined : Request
+  : never
+
+type UrlBuilderArgs<Endpoint extends HttpApiEndpoint.Any> = [UrlBuilderRequest<Endpoint>] extends [void | undefined] ?
+  [request?: UrlBuilderRequest<Endpoint>]
+  : [request: UrlBuilderRequest<Endpoint>]
+
+/**
+ * @since 4.0.0
+ * @category models
+ */
+export type UrlBuilder<Api extends HttpApi.Any> = Api extends HttpApi.HttpApi<infer _ApiId, infer Groups> ? Simplify<
+    & {
+      readonly [Group in Extract<Groups, { readonly topLevel: false }> as HttpApiGroup.Name<Group>]: UrlBuilderGroup<
+        HttpApiGroup.Endpoints<Group>
+      >
+    }
+    & {
+      readonly [Method in UrlBuilderTopLevelMethods<Groups> as Method[0]]: Method[1]
+    }
+  >
+  : never
+
+type UrlBuilderGroup<Endpoints extends HttpApiEndpoint.Any> = {
+  readonly [Endpoint in Endpoints as HttpApiEndpoint.Name<Endpoint>]: UrlBuilderMethod<Endpoint>
+}
+
+type UrlBuilderMethod<Endpoint extends HttpApiEndpoint.Any> = (
+  ...args: UrlBuilderArgs<Endpoint>
+) => string
+
+type UrlBuilderTopLevelMethods<Groups extends HttpApiGroup.Any> = Extract<Groups, { readonly topLevel: true }> extends
+  HttpApiGroup.HttpApiGroup<infer _Id, infer _Endpoints, infer _TopLevel> ?
+  _Endpoints extends infer Endpoint extends HttpApiEndpoint.Any ?
+    [HttpApiEndpoint.Name<Endpoint>, UrlBuilderMethod<Endpoint>]
+  : never :
+  never
+
 const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>(
   api: HttpApi.HttpApi<ApiId, Groups>,
   options: {
@@ -128,7 +192,7 @@ const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>
       readonly group: HttpApiGroup.AnyWithProps
       readonly endpoint: HttpApiEndpoint.AnyWithProps
       readonly mergedAnnotations: ServiceMap.ServiceMap<never>
-      readonly middleware: ReadonlySet<HttpApiMiddleware.AnyKey>
+      readonly middleware: ReadonlySet<HttpApiMiddleware.AnyService>
       readonly successes: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
       readonly errors: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
       readonly endpointFn: Function
@@ -217,17 +281,17 @@ const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>
         })
 
         // encoders
-        const encodeParams = UndefinedOr.map(HttpApiEndpoint.getParamsSchema(endpoint), Schema.encodeUnknownEffect)
+        const encodeParams = UndefinedOr.map(endpoint.params, Schema.encodeUnknownEffect)
 
         const payloadSchemas = HttpApiEndpoint.getPayloadSchemas(endpoint)
         const encodePayload = Arr.isArrayNonEmpty(payloadSchemas) ?
           HttpMethod.hasBody(endpoint.method)
-            ? Schema.encodeUnknownEffect(getEncodePayloadSchema(payloadSchemas))
+            ? Schema.encodeUnknownEffect(getEncodePayloadSchema(payloadSchemas, endpoint.method))
             : Schema.encodeUnknownEffect(Schema.Union(payloadSchemas)) :
           undefined
 
-        const encodeHeaders = UndefinedOr.map(HttpApiEndpoint.getHeadersSchema(endpoint), Schema.encodeUnknownEffect)
-        const encodeQuery = UndefinedOr.map(HttpApiEndpoint.getQuerySchema(endpoint), Schema.encodeUnknownEffect)
+        const encodeHeaders = UndefinedOr.map(endpoint.headers, Schema.encodeUnknownEffect)
+        const encodeQuery = UndefinedOr.map(endpoint.query, Schema.encodeUnknownEffect)
 
         const middlewareKeys = Array.from(onEndpointOptions.middleware, (tag) => `${tag.key}/Client`)
 
@@ -237,7 +301,7 @@ const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>
             readonly query: unknown
             readonly payload: unknown
             readonly headers: Record<string, string> | undefined
-            readonly withResponse?: boolean
+            readonly responseMode?: HttpApiEndpoint.ClientResponseMode
           } | undefined
         ) {
           let httpRequest = HttpClientRequest.make(endpoint.method)(endpoint.path)
@@ -285,11 +349,15 @@ const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Any, E, R>
             middlewareKeys.length - 1
           )
 
+          if (request?.responseMode === "response-only") {
+            return response
+          }
+
           const value = yield* (options.transformResponse === undefined
             ? decodeResponse(response)
             : options.transformResponse(decodeResponse(response)))
 
-          return request?.withResponse === true ? [value, response] : value
+          return request?.responseMode === "decoded-and-response" ? [value, response] : value
         })
 
         options.onEndpoint({
@@ -314,7 +382,7 @@ export const make = <ApiId extends string, Groups extends HttpApiGroup.Any>(
     readonly baseUrl?: URL | string | undefined
   }
 ): Effect.Effect<
-  Client<Groups, HttpApiSchemaError, never>,
+  Client<Groups>,
   never,
   HttpClient.HttpClient | HttpApiGroup.MiddlewareClient<Groups>
 > =>
@@ -337,7 +405,7 @@ export const makeWith = <ApiId extends string, Groups extends HttpApiGroup.Any,
       | undefined
     readonly baseUrl?: URL | string | undefined
   }
-): Effect.Effect<Client<Groups, HttpApiSchemaError | E, R>, never, HttpApiGroup.MiddlewareClient<Groups>> => {
+): Effect.Effect<Client<Groups, BadRequest | E, R>, never, HttpApiGroup.MiddlewareClient<Groups>> => {
   const client: Record<string, Record<string, any>> = {}
   return makeClient(api, {
     ...options,
@@ -372,7 +440,7 @@ export const group = <
     readonly baseUrl?: URL | string | undefined
   }
 ): Effect.Effect<
-  Client.Group<Groups, GroupName, HttpApiSchemaError | E, R>,
+  Client.Group<Groups, GroupName, BadRequest | E, R>,
   never,
   HttpApiGroup.MiddlewareClient<HttpApiGroup.WithName<Groups, GroupName>>
 > => {
@@ -412,7 +480,7 @@ export const endpoint = <
 ): Effect.Effect<
   Client.Method<
     HttpApiEndpoint.WithName<HttpApiGroup.Endpoints<HttpApiGroup.WithName<Groups, GroupName>>, EndpointName>,
-    HttpApiSchemaError | E,
+    BadRequest | E,
     R
   >,
   never,
@@ -430,6 +498,75 @@ export const endpoint = <
   }).pipe(Effect.map(() => client)) as any
 }
 
+/**
+ * Creates a type-safe URL builder that mirrors `HttpApiClient.make`.
+ *
+ * @example
+ * ```ts
+ * import { Schema } from "effect"
+ * import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi"
+ *
+ * const Api = HttpApi.make("Api").add(
+ *   HttpApiGroup.make("users").add(
+ *     HttpApiEndpoint.get("getUser", "/users/:id", {
+ *       params: { id: Schema.String }
+ *     })
+ *   )
+ * )
+ *
+ * const buildUrl = HttpApiClient.urlBuilder(Api, {
+ *   baseUrl: "https://api.example.com"
+ * })
+ *
+ * buildUrl.users.getUser({
+ *   params: { id: "123" }
+ * })
+ * //=> "https://api.example.com/users/123"
+ * ```
+ * @since 4.0.0
+ * @category constructors
+ */
+export const urlBuilder = <Api extends HttpApi.Any>(api: Api, options?: {
+  readonly baseUrl?: URL | string | undefined
+}): UrlBuilder<Api> => {
+  const builder: Record<string, any> = {}
+
+  HttpApi.reflect(api as unknown as HttpApi.AnyWithProps, {
+    onGroup({ group }) {
+      if (group.topLevel) return
+      builder[group.identifier] = {}
+    },
+    onEndpoint({ group, endpoint }) {
+      const makeUrl = compilePath(endpoint.path)
+      const encodeParams = endpoint.params === undefined
+        ? undefined
+        : Schema.encodeSync(endpoint.params as Schema.Encoder<unknown>)
+      const encodeQuery = endpoint.query === undefined
+        ? undefined
+        : Schema.encodeSync(endpoint.query as Schema.Encoder<unknown>)
+
+      const endpointBuilder = (request?: {
+        readonly params?: unknown
+        readonly query?: unknown
+      }) => {
+        const params = request?.params
+        const path = params === undefined
+          ? endpoint.path
+          : makeUrl((encodeParams === undefined ? params : encodeParams(params)) as Record<string, string | undefined>)
+        const queryInput = request?.query === undefined
+          ? undefined
+          : (encodeQuery === undefined ? request.query : encodeQuery(request.query)) as UrlParams.Input
+        const query = queryInput === undefined ? "" : UrlParams.toString(UrlParams.fromInput(queryInput))
+        const url = query === "" ? path : `${path}?${query}`
+        return options?.baseUrl === undefined ? url : new URL(url, options.baseUrl.toString()).toString()
+      }
+      ;(group.topLevel ? builder : builder[group.identifier])[endpoint.name] = endpointBuilder
+    }
+  })
+
+  return builder as UrlBuilder<Api>
+}
+
 // ----------------------------------------------------------------------------
 
 const paramsRegExp = /:(\w+)\??/g
@@ -440,7 +577,7 @@ const compilePath = (path: string) => {
   if (len === 1) {
     return (_: any) => path
   }
-  return (params: Record<string, string>) => {
+  return (params: Record<string, string | undefined>) => {
     let url = segments[0]
     for (let i = 1; i < len; i++) {
       if (i % 2 === 0) {
@@ -519,8 +656,19 @@ function toCodecArrayBuffer(schemas: readonly [Schema.Top, ...Array<Schema.Top>]
   function onSchema(schema: Schema.Top) {
     const encoding = HttpApiSchema.getResponseEncoding(schema.ast)
     switch (encoding._tag) {
-      case "Json":
-        return UnknownFromArrayBuffer.pipe(Schema.decodeTo(schema))
+      case "Json": {
+        // handle json codecs that transform void schemas to null
+        const encodedIsNull = AST.isNull(AST.toEncoded(schema.ast))
+        return UnknownFromArrayBuffer.pipe(Schema.decodeTo(
+          schema,
+          encodedIsNull ?
+            Transformation.transform({
+              decode: (a) => a === undefined ? null : a,
+              encode: (a) => a === null ? undefined : a
+            }) as any :
+            undefined
+        ))
+      }
       case "FormUrlEncoded":
         return StringFromArrayBuffer.pipe(
           Schema.decodeTo(UrlParams.schemaRecord),
@@ -546,21 +694,25 @@ const statusOrElse = (response: HttpClientResponse.HttpClientResponse) =>
 
 const $HttpBody = Schema.declare(HttpBody.isHttpBody)
 
-function getEncodePayloadSchema(schemas: readonly [Schema.Top, ...Array<Schema.Top>]): Schema.Top {
-  return Schema.Union(schemas.map(getEncodePayloadSchemaFromBody))
+function getEncodePayloadSchema(
+  schemas: readonly [Schema.Top, ...Array<Schema.Top>],
+  method: HttpMethod.HttpMethod
+): Schema.Top {
+  return Schema.Union(schemas.map((s) => getEncodePayloadSchemaFromBody(s, method)))
 }
 
 const bodyFromPayloadCache = new WeakMap<AST.AST, Schema.Top>()
 
 function getEncodePayloadSchemaFromBody(
-  schema: Schema.Top
+  schema: Schema.Top,
+  method: HttpMethod.HttpMethod
 ): Schema.Top {
   const ast = schema.ast
   const cached = bodyFromPayloadCache.get(ast)
   if (cached !== undefined) {
     return cached
   }
-  const encoding = HttpApiSchema.getPayloadEncoding(ast)
+  const encoding = HttpApiSchema.getPayloadEncoding(ast, method)
   const out = $HttpBody.pipe(Schema.decodeTo(
     schema,
     Transformation.transformOrFail({