feat: setOptions / setEndpointOptions + Api.Options rename (#600)

* feat: setOptions / setEndpointOptions functions

* refactor: rename `Api.ApiOptions` to `Api.Options`

.changeset/heavy-ads-check.md

@@ -0,0 +1,5 @@
+---
+"effect-http": patch
+---
+
+Add `Api.setOptions`, `Api.setEndpointOptions`, `ApiGroup.setOptions`, `ApiGroup.setEndpointOptions` and `ApiEndpoint.setOptions`.

.changeset/selfish-mugs-develop.md

@@ -0,0 +1,5 @@
+---
+"effect-http": minor
+---
+
+Rename `Api.ApiOptions` to `Api.Options`.

packages/effect-http/dtslint/Api.ts

@@ -0,0 +1,22 @@
+import { Api } from "effect-http"
+
+// $ExpectType Api<never>
+Api.make().pipe(
+  Api.setOptions({ title: "My API" })
+)
+
+// $ExpectType Api<Default<"hello">>
+Api.make().pipe(
+  Api.addEndpoint(Api.get("hello", "/hello")),
+  Api.setOptions({ title: "My API" })
+)
+
+// $ExpectType Api<Default<"hello">>
+Api.make().pipe(
+  Api.addEndpoint(
+    Api.get("hello", "/hello").pipe(
+      Api.setEndpointOptions({ description: "My endpoint" })
+    )
+  ),
+  Api.setOptions({ title: "My API" })
+)

packages/effect-http/dtslint/ApiEndpoint.ts

@@ -0,0 +1,6 @@
+import { ApiEndpoint } from "effect-http"
+
+// $ExpectType Default<"hello">
+ApiEndpoint.get("hello", "/hello").pipe(
+  ApiEndpoint.setOptions({ description: "my endpoint" })
+)

packages/effect-http/dtslint/ApiGroup.ts

@@ -0,0 +1,16 @@
+import { ApiGroup } from "effect-http"
+
+// $ExpectType ApiGroup<never>
+ApiGroup.make("myGroup").pipe(
+  ApiGroup.setOptions({ description: "My group" })
+)
+
+// $ExpectType ApiGroup<Default<"hello">>
+ApiGroup.make("myGroup").pipe(
+  ApiGroup.addEndpoint(
+    ApiGroup.get("hello", "/hello").pipe(
+      ApiGroup.setEndpointOptions({ description: "My endpoint" })
+    )
+  ),
+  ApiGroup.setOptions({ description: "My group" })
+)

packages/effect-http/dtslint/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["."],
+  "compilerOptions": {
+    "incremental": false,
+    "composite": false,
+    "noUnusedLocals": false
+  }
+}

packages/effect-http/package.json

@@ -19,13 +19,14 @@
     "directory": "dist"
   },
   "scripts": {
+    "check": "tsc -b tsconfig.json",
+    "check:watch": "tsc -b tsconfig.json --watch",
     "codegen": "build-utils prepare-v2",
     "build": "pnpm codegen && pnpm build-esm && pnpm build-cjs && pnpm build-annotate && build-utils pack-v2",
     "build-esm": "tsc -b tsconfig.build.json",
     "build-cjs": "babel build/esm --plugins @babel/transform-export-namespace-from --plugins @babel/transform-modules-commonjs --out-dir build/cjs --source-maps",
     "build-annotate": "babel build --plugins annotate-pure-calls --out-dir build --source-maps",
-    "check": "tsc -b tsconfig.json",
-    "check:watch": "tsc -b tsconfig.json --watch",
+    "dtslint": "dtslint dtslint",
     "test": "vitest",
     "coverage": "vitest --coverage"
   },

packages/effect-http/src/Api.ts

@@ -29,7 +29,7 @@ export type TypeId = typeof TypeId
  * @category models
  * @since 1.0.0
  */
-export interface ApiOptions {
+export interface Options {
   readonly title: string
   readonly version: string
   readonly description?: string
@@ -46,7 +46,7 @@ export interface ApiOptions {
  */
 export interface Api<A extends ApiEndpoint.ApiEndpoint.Any> extends Pipeable.Pipeable, Api.Variance<A> {
   readonly groups: ReadonlyArray<ApiGroup.ApiGroup<A>>
-  readonly options: ApiOptions
+  readonly options: Options
 }
 
 /**
@@ -114,7 +114,7 @@ export declare namespace Api {
  * @category constructors
  * @since 1.0.0
  */
-export const make: (options?: Partial<ApiOptions>) => Api.Empty = internal.make
+export const make: (options?: Partial<Options>) => Api.Empty = internal.make
 
 /**
  * @category combining
@@ -175,6 +175,11 @@ export {
    * @since 1.0.0
    */
   put,
+  /**
+   * @category modifications
+   * @since 1.0.0
+   */
+  setOptions as setEndpointOptions,
   /**
    * @category constructors
    * @since 1.0.0
@@ -230,12 +235,16 @@ export {
    * @since 1.0.0
    */
   setSecurity
-  /**
-   * @category modifications
-   * @since 1.0.0
-   */
 } from "./ApiEndpoint.js"
 
+/**
+ * @category combining
+ * @since 1.0.0
+ */
+export const setOptions: (
+  options: Partial<Options>
+) => <A extends ApiEndpoint.ApiEndpoint.Any>(self: Api<A>) => Api<A> = internal.setOptions
+
 /**
  * FormData schema
  *

packages/effect-http/src/ApiEndpoint.ts

@@ -337,6 +337,13 @@ export const setSecurity: <Security extends Security.Security.Any>(security: Sec
 >(endpoint: ApiEndpoint<Id, Request, Response, _>) => ApiEndpoint<Id, Request, Response, Security> =
   internal.setSecurity
 
+/**
+ * @category modifications
+ * @since 1.0.0
+ */
+export const setOptions: (options: Partial<Options>) => <A extends ApiEndpoint.Any>(endpoint: A) => A =
+  internal.setOptions
+
 /**
  * @category modifications
  * @since 1.0.0

packages/effect-http/src/ApiGroup.ts

@@ -135,6 +135,11 @@ export {
    * @since 1.0.0
    */
   put,
+  /**
+   * @category modifications
+   * @since 1.0.0
+   */
+  setOptions as setEndpointOptions,
   /**
    * @category constructors
    * @since 1.0.0
@@ -190,12 +195,16 @@ export {
    * @since 1.0.0
    */
   setSecurity
-  /**
-   * @category modifications
-   * @since 1.0.0
-   */
 } from "./ApiEndpoint.js"
 
+/**
+ * @category modifications
+ * @since 1.0.0
+ */
+export const setOptions: (
+  options: Partial<Options>
+) => <A extends ApiEndpoint.ApiEndpoint.Any>(api: ApiGroup<A>) => ApiGroup<A> = internal.setOptions
+
 /**
  * @category refinements
  * @since 1.0.0

packages/effect-http/src/internal/api-endpoint.ts

@@ -201,6 +201,19 @@ export const setSecurity = <Security extends Security.Security.Any>(
     getOptions(endpoint)
   )
 
+/** @internal */
+export const setOptions =
+  (options: Partial<ApiEndpoint.Options>) => <A extends ApiEndpoint.ApiEndpoint.Any>(endpoint: A): A =>
+    new ApiEndpointImpl(
+      getId(endpoint),
+      getPath(endpoint),
+      getMethod(endpoint),
+      getRequest(endpoint),
+      getResponse(endpoint),
+      getSecurity(endpoint),
+      { ...getOptions(endpoint), ...options }
+    ) as unknown as A
+
 /** @internal */
 export const getId = <
   Id extends ApiEndpoint.ApiEndpoint.AnyId,

packages/effect-http/src/internal/api-group.ts

@@ -22,8 +22,8 @@ export class ApiGroupImpl<Endpoints extends ApiEndpoint.ApiEndpoint.Any> impleme
 
   constructor(
     readonly name: string,
-    readonly endpoints: Array<Endpoints>,
-    readonly options: ApiGroup.ApiGroup.Any["options"]
+    readonly endpoints: ReadonlyArray<Endpoints>,
+    readonly options: ApiGroup.Options
   ) {}
 
   pipe() {
@@ -36,7 +36,7 @@ export class ApiGroupImpl<Endpoints extends ApiEndpoint.ApiEndpoint.Any> impleme
 export const isApiGroup = (u: unknown): u is ApiGroup.ApiGroup.Any => typeof u === "object" && u !== null && TypeId in u
 
 /** @internal */
-export const make = (name: string, options?: Partial<Api.ApiOptions>): ApiGroup.ApiGroup.Empty =>
+export const make = (name: string, options?: Partial<Api.Options>): ApiGroup.ApiGroup.Empty =>
   new ApiGroupImpl(name, [], { ...options })
 
 /** @internal */
@@ -58,3 +58,9 @@ export const addEndpoint =
 
     return new ApiGroupImpl(self.name, [...self.endpoints, endpoint], self.options)
   }
+
+/** @internal */
+export const setOptions =
+  (options: Partial<ApiGroup.Options>) =>
+  <A extends ApiEndpoint.ApiEndpoint.Any>(self: ApiGroup.ApiGroup<A>): ApiGroup.ApiGroup<A> =>
+    new ApiGroupImpl(self.name, self.endpoints, { ...self.options, ...options })

packages/effect-http/src/internal/api.ts

@@ -42,7 +42,7 @@ const DEFAULT_API_OPTIONS: Api.Api.Any["options"] = {
 export const isApi = (u: unknown): u is Api.Api.Any => typeof u === "object" && u !== null && TypeId in u
 
 /** @internal */
-export const make = (options?: Partial<Api.ApiOptions>): Api.Api.Empty =>
+export const make = (options?: Partial<Api.Options>): Api.Api.Empty =>
   new ApiImpl([], { ...DEFAULT_API_OPTIONS, ...options })
 
 /** @internal */
@@ -90,3 +90,8 @@ export const getEndpoint = <A extends Api.Api.Any, Id extends Api.Api.Ids<A>>(
 
   return endpoint as Api.Api.EndpointById<A, Id>
 }
+
+/** @internal */
+export const setOptions =
+  (options: Partial<Api.Options>) => <A extends ApiEndpoint.ApiEndpoint.Any>(self: Api.Api<A>): Api.Api<A> =>
+    new ApiImpl(self.groups, { ...self.options, ...options })