effect 4.0.0-beta.97 → 4.0.0-beta.98

package/src/unstable/httpapi/HttpApiError.ts

@@ -27,6 +27,7 @@ const notAcceptableResponse = HttpServerResponse.empty({ status: 406 })
 const requestTimeoutResponse = HttpServerResponse.empty({ status: 408 })
 const conflictResponse = HttpServerResponse.empty({ status: 409 })
 const goneResponse = HttpServerResponse.empty({ status: 410 })
+const unprocessableEntityResponse = HttpServerResponse.empty({ status: 422 })
 const internalServerErrorResponse = HttpServerResponse.empty({ status: 500 })
 const notImplementedResponse = HttpServerResponse.empty({ status: 501 })
 const serviceUnavailableResponse = HttpServerResponse.empty({ status: 503 })
@@ -302,6 +303,38 @@ export const GoneNoContent = Gone.pipe(HttpApiSchema.asNoContent({
   decode: () => new Gone({})
 }))
 
+/**
+ * Built-in HTTP API error for a `422 Unprocessable Entity` response. When used
+ * directly as a server response, it renders as an empty response with status 422.
+ *
+ * @category errors
+ * @since 4.0.0
+ */
+export class UnprocessableEntity
+  extends Schema.ErrorClass<UnprocessableEntity>("effect/HttpApiError/UnprocessableEntity")({
+    _tag: Schema.tag("UnprocessableEntity")
+  }, {
+    description: "UnprocessableEntity",
+    httpApiStatus: 422
+  })
+{
+  override readonly [ErrorReporter.ignore] = true;
+  [HttpServerRespondable.symbol]() {
+    return Effect.succeed(unprocessableEntityResponse)
+  }
+}
+
+/**
+ * No-content schema variant for `UnprocessableEntity`, decoding an empty 422
+ * response into an `UnprocessableEntity` error value.
+ *
+ * @category NoContent errors
+ * @since 4.0.0
+ */
+export const UnprocessableEntityNoContent = UnprocessableEntity.pipe(HttpApiSchema.asNoContent({
+  decode: () => new UnprocessableEntity({})
+}))
+
 /**
  * Built-in HTTP API error for a `500 Internal Server Error` response. When used
  * directly as a server response, it renders as an empty response with status 500.

package/src/unstable/httpapi/HttpApiGroup.ts

@@ -12,6 +12,7 @@
  */
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Context from "../../Context.ts"
+import * as internalRecord from "../../internal/record.ts"
 import { type Pipeable, pipeArguments } from "../../Pipeable.ts"
 import * as Predicate from "../../Predicate.ts"
 import * as Record from "../../Record.ts"
@@ -28,7 +29,14 @@ const TypeId = "~effect/httpapi/HttpApiGroup"
  * @category guards
  * @since 4.0.0
  */
-export const isHttpApiGroup = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
+export const isHttpApiGroup = (u: unknown): u is Top => Predicate.hasProperty(u, TypeId)
+
+/**
+ * Endpoints indexed by their identifier.
+ */
+type EndpointMap<Endpoints extends HttpApiEndpoint.Constraint> = {
+  readonly [Endpoint in Endpoints as HttpApiEndpoint.Identifier<Endpoint>]: Endpoint
+}
 
 /**
  * An `HttpApiGroup` is a named collection of `HttpApiEndpoint`s that represents
@@ -43,21 +51,26 @@ export const isHttpApiGroup = (u: unknown): u is Any => Predicate.hasProperty(u,
  */
 export interface HttpApiGroup<
   out Id extends string,
-  out Endpoints extends HttpApiEndpoint.Any = never,
+  in out Endpoints extends HttpApiEndpoint.Constraint = never,
   out TopLevel extends boolean = false
 > extends Pipeable {
   new(_: never): {}
   readonly [TypeId]: typeof TypeId
+  /**
+   * Stable group identifier. This field intentionally is not named `name`
+   * because `HttpApiGroup` values can be extended as classes, where `name`
+   * would collide with JavaScript's built-in `Function.name`.
+   */
   readonly identifier: Id
   readonly key: string
   readonly topLevel: TopLevel
-  readonly endpoints: Record.ReadonlyRecord<string, Endpoints>
+  readonly endpoints: EndpointMap<Endpoints>
   readonly annotations: Context.Context<never>
 
   /**
    * Add an `HttpApiEndpoint` to an `HttpApiGroup`.
    */
-  add<const A extends NonEmptyReadonlyArray<HttpApiEndpoint.Any>>(
+  add<const A extends NonEmptyReadonlyArray<HttpApiEndpoint.Constraint>>(
     ...endpoints: A
   ): HttpApiGroup<Id, Endpoints | A[number], TopLevel>
 
@@ -113,50 +126,63 @@ export interface HttpApiGroup<
 }
 
 /**
- * Type-level identity for a group within an HTTP API, pairing the API id with the
- * group name for service derivation.
+ * Type-level service produced by the layer that implements one group of an HTTP
+ * API.
+ *
+ * **Details**
+ *
+ * `HttpApiBuilder.group` provides this service, and `HttpApiBuilder.layer`
+ * requires one service for each group in the API. The type carries both the API
+ * id and the group identifier so the relationship between an API and its
+ * implemented groups is checked at compile time.
  *
  * @category models
  * @since 4.0.0
  */
-export interface ApiGroup<ApiId extends string, Name extends string> {
+export interface Service<ApiId extends string, Identifier extends string> {
   readonly _: unique symbol
   readonly apiId: ApiId
-  readonly name: Name
+  readonly identifier: Identifier
 }
 
 /**
- * A widened `HttpApiGroup` type used when the concrete group name, endpoints, and
- * top-level flag are not needed.
+ * Derives the group implementation service required for each group in an HTTP
+ * API.
+ *
+ * **Details**
+ *
+ * When given an API id and a group or union of groups, this type maps each group
+ * to the `Service` identity that must be provided by `HttpApiBuilder.group`.
  *
  * @category models
  * @since 4.0.0
  */
-export interface Any {
-  readonly [TypeId]: typeof TypeId
-  readonly identifier: string
-  readonly key: string
-  readonly endpoints: Record.ReadonlyRecord<string, HttpApiEndpoint.Any>
-}
+export type ToService<ApiId extends string, Group extends Constraint> = Group extends Constraint ?
+  Service<ApiId, Group["identifier"]>
+  : never
 
 /**
- * A widened group type that preserves concrete runtime properties such as
- * identifier, key, top-level status, endpoints, and annotations.
+ * A widened `HttpApiGroup` type used when the concrete group identifier,
+ * endpoints, and top-level flag are not needed.
  *
  * @category models
  * @since 4.0.0
  */
-export type AnyWithProps = HttpApiGroup<string, HttpApiEndpoint.AnyWithProps, boolean>
+export interface Constraint {
+  readonly [TypeId]: typeof TypeId
+  readonly identifier: string
+  readonly key: string
+  readonly endpoints: Record.ReadonlyRecord<string, HttpApiEndpoint.Constraint>
+}
 
 /**
- * Derives the API-specific `ApiGroup` service identity for an HTTP API group.
+ * A widened group type that preserves concrete runtime properties such as
+ * identifier, key, top-level status, endpoints, and annotations.
  *
  * @category models
  * @since 4.0.0
  */
-export type ToService<ApiId extends string, A> = A extends HttpApiGroup<infer Name, infer _Endpoints, infer _TopLevel> ?
-  ApiGroup<ApiId, Name>
-  : never
+export interface Top extends HttpApiGroup<string, HttpApiEndpoint.Top, boolean> {}
 
 /**
  * Selects the group with the specified identifier from a union of groups.
@@ -164,7 +190,7 @@ export type ToService<ApiId extends string, A> = A extends HttpApiGroup<infer Na
  * @category models
  * @since 4.0.0
  */
-export type WithName<Group, Name extends string> = Extract<Group, { readonly identifier: Name }>
+export type WithIdentifier<Group, Identifier extends string> = Extract<Group, { readonly identifier: Identifier }>
 
 /**
  * Extracts the identifier literal from an `HttpApiGroup`.
@@ -172,8 +198,7 @@ export type WithName<Group, Name extends string> = Extract<Group, { readonly ide
  * @category models
  * @since 4.0.0
  */
-export type Name<Group> = Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel> ? _Name
-  : never
+export type Identifier<Group> = Group extends Constraint ? Group["identifier"] : never
 
 /**
  * Extracts the endpoint union contained in an `HttpApiGroup`.
@@ -181,7 +206,8 @@ export type Name<Group> = Group extends HttpApiGroup<infer _Name, infer _Endpoin
  * @category models
  * @since 4.0.0
  */
-export type Endpoints<Group> = Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel> ? _Endpoints
+export type Endpoints<Group> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ?
+  _Endpoints
   : never
 
 /**
@@ -236,12 +262,14 @@ export type MiddlewareClient<Group> = HttpApiEndpoint.MiddlewareClient<Endpoints
 export type MiddlewareServices<Group> = HttpApiEndpoint.MiddlewareServices<Endpoints<Group>>
 
 /**
- * Selects the endpoints in a group whose `name` matches the provided endpoint name.
+ * Extracts the endpoint union from the group with the specified identifier.
  *
  * @category models
  * @since 4.0.0
  */
-export type EndpointsWithName<Group extends Any, Name extends string> = Endpoints<WithName<Group, Name>>
+export type EndpointsWithIdentifier<Group extends Constraint, Identifier extends string> = Endpoints<
+  WithIdentifier<Group, Identifier>
+>
 
 /**
  * Computes the schema encoding and decoding services required by clients for all endpoints in a group.
@@ -249,7 +277,7 @@ export type EndpointsWithName<Group extends Any, Name extends string> = Endpoint
  * @category models
  * @since 4.0.0
  */
-export type ClientServices<Group> = Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel> ?
+export type ClientServices<Group> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ?
   HttpApiEndpoint.ClientServices<_Endpoints>
   : never
 
@@ -260,8 +288,8 @@ export type ClientServices<Group> = Group extends HttpApiGroup<infer _Name, infe
  * @since 4.0.0
  */
 export type AddPrefix<Group, Prefix extends PathInput> = Group extends
-  HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel> ?
-  HttpApiGroup<_Name, HttpApiEndpoint.AddPrefix<_Endpoints, Prefix>, _TopLevel>
+  HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ?
+  HttpApiGroup<_Identifier, HttpApiEndpoint.AddPrefix<_Endpoints, Prefix>, _TopLevel>
   : never
 
 /**
@@ -271,70 +299,56 @@ export type AddPrefix<Group, Prefix extends PathInput> = Group extends
  * @since 4.0.0
  */
 export type AddMiddleware<Group, Id extends HttpApiMiddleware.AnyId> = Group extends
-  HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel> ?
-  HttpApiGroup<_Name, HttpApiEndpoint.AddMiddleware<_Endpoints, Id>, _TopLevel>
+  HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ?
+  HttpApiGroup<_Identifier, HttpApiEndpoint.AddMiddleware<_Endpoints, Id>, _TopLevel>
   : never
 
 const Proto = {
   [TypeId]: TypeId,
-  add(this: AnyWithProps, ...toAdd: NonEmptyReadonlyArray<HttpApiEndpoint.AnyWithProps>) {
+  add(this: Top, ...toAdd: NonEmptyReadonlyArray<HttpApiEndpoint.Top>) {
     const endpoints = { ...this.endpoints }
     for (const endpoint of toAdd) {
-      endpoints[endpoint.name] = endpoint
+      internalRecord.set(endpoints, endpoint.identifier, endpoint)
     }
     return makeProto({
-      identifier: this.identifier,
-      topLevel: this.topLevel,
-      endpoints,
-      annotations: this.annotations
+      ...optionsFromGroup(this),
+      endpoints
     })
   },
-  prefix(this: AnyWithProps, prefix: PathInput) {
+  prefix(this: Top, prefix: PathInput) {
     return makeProto({
-      identifier: this.identifier,
-      topLevel: this.topLevel,
-      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.prefix(prefix)),
-      annotations: this.annotations
+      ...optionsFromGroup(this),
+      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.prefix(prefix))
     })
   },
-  middleware(this: AnyWithProps, middleware: HttpApiMiddleware.AnyService) {
+  middleware(this: Top, middleware: HttpApiMiddleware.AnyService) {
     return makeProto({
-      identifier: this.identifier,
-      topLevel: this.topLevel,
-      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.middleware(middleware as any)),
-      annotations: this.annotations
+      ...optionsFromGroup(this),
+      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.middleware(middleware as any))
     })
   },
-  annotateMerge<I>(this: AnyWithProps, annotations: Context.Context<I>) {
+  annotateMerge<I>(this: Top, annotations: Context.Context<I>) {
     return makeProto({
-      identifier: this.identifier,
-      topLevel: this.topLevel,
-      endpoints: this.endpoints,
+      ...optionsFromGroup(this),
       annotations: Context.merge(this.annotations, annotations)
     })
   },
-  annotate<I, S>(this: AnyWithProps, annotation: Context.Key<I, S>, value: S) {
+  annotate<I, S>(this: Top, annotation: Context.Key<I, S>, value: S) {
     return makeProto({
-      identifier: this.identifier,
-      topLevel: this.topLevel,
-      endpoints: this.endpoints,
+      ...optionsFromGroup(this),
       annotations: Context.add(this.annotations, annotation, value)
     })
   },
-  annotateEndpointsMerge<I>(this: AnyWithProps, annotations: Context.Context<I>) {
+  annotateEndpointsMerge<I>(this: Top, annotations: Context.Context<I>) {
     return makeProto({
-      identifier: this.identifier,
-      topLevel: this.topLevel,
-      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.annotateMerge(annotations)),
-      annotations: this.annotations
+      ...optionsFromGroup(this),
+      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.annotateMerge(annotations))
     })
   },
-  annotateEndpoints<I, S>(this: AnyWithProps, annotation: Context.Key<I, S>, value: S) {
+  annotateEndpoints<I, S>(this: Top, annotation: Context.Key<I, S>, value: S) {
     return makeProto({
-      identifier: this.identifier,
-      topLevel: this.topLevel,
-      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.annotate(annotation, value)),
-      annotations: this.annotations
+      ...optionsFromGroup(this),
+      endpoints: Record.map(this.endpoints, (endpoint) => endpoint.annotate(annotation, value))
     })
   },
   pipe() {
@@ -342,14 +356,21 @@ const Proto = {
   }
 }
 
+const optionsFromGroup = (group: Top) => ({
+  identifier: group.identifier,
+  topLevel: group.topLevel,
+  endpoints: group.endpoints,
+  annotations: group.annotations
+})
+
 const makeProto = <
   Id extends string,
-  Endpoints extends HttpApiEndpoint.Any,
+  Endpoints extends HttpApiEndpoint.Constraint,
   TopLevel extends (true | false)
 >(options: {
   readonly identifier: Id
   readonly topLevel: TopLevel
-  readonly endpoints: Record.ReadonlyRecord<string, Endpoints>
+  readonly endpoints: Record.ReadonlyRecord<string, HttpApiEndpoint.Constraint>
   readonly annotations: Context.Context<never>
 }): HttpApiGroup<Id, Endpoints, TopLevel> => {
   function HttpApiGroup() {}
@@ -365,7 +386,7 @@ const makeProto = <
  *
  * Add endpoints with `add`, provide implementations with `HttpApiBuilder.group`,
  * and set `topLevel` when the generated client should expose endpoint methods
- * directly instead of nesting them under the group name.
+ * directly instead of nesting them under the group identifier.
  *
  * @category constructors
  * @since 4.0.0
@@ -375,7 +396,7 @@ export const make = <const Id extends string, const TopLevel extends boolean = f
 }): HttpApiGroup<Id, never, TopLevel> =>
   makeProto({
     identifier,
-    topLevel: options?.topLevel ?? false as any,
-    endpoints: Record.empty(),
+    topLevel: (options?.topLevel ?? false) as TopLevel,
+    endpoints: {},
     annotations: Context.empty()
-  }) as any
+  })

package/src/unstable/httpapi/HttpApiMiddleware.ts

@@ -64,8 +64,8 @@ type ErrorSchemaFromConstraint<E> = E extends ReadonlyArray<Schema.Constraint> ?
 export type HttpApiMiddleware<Provides, E extends ErrorConstraint, Requires> = (
   httpEffect: Effect.Effect<HttpServerResponse, unhandled, Provides>,
   options: {
-    readonly endpoint: HttpApiEndpoint.AnyWithProps
-    readonly group: HttpApiGroup.AnyWithProps
+    readonly endpoint: HttpApiEndpoint.Top
+    readonly group: HttpApiGroup.Top
   }
 ) => Effect.Effect<HttpServerResponse, unhandled | ErrorSchemaFromConstraint<E>["Type"], Requires | HttpRouter.Provided>
 
@@ -90,8 +90,8 @@ export type HttpApiMiddlewareSecurity<
     httpEffect: Effect.Effect<HttpServerResponse, unhandled, Provides>,
     options: {
       readonly credential: HttpApiSecurity.HttpApiSecurity.Type<Security[K]>
-      readonly endpoint: HttpApiEndpoint.AnyWithProps
-      readonly group: HttpApiGroup.AnyWithProps
+      readonly endpoint: HttpApiEndpoint.Top
+      readonly group: HttpApiGroup.Top
     }
   ) => Effect.Effect<
     HttpServerResponse,
@@ -113,8 +113,8 @@ export type HttpApiMiddlewareSecurity<
  */
 export interface HttpApiMiddlewareClient<_E, CE, R> {
   (options: {
-    readonly endpoint: HttpApiEndpoint.AnyWithProps
-    readonly group: HttpApiGroup.AnyWithProps
+    readonly endpoint: HttpApiEndpoint.Top
+    readonly group: HttpApiGroup.Top
     readonly request: HttpClientRequest.HttpClientRequest
     readonly next: (
       request: HttpClientRequest.HttpClientRequest
@@ -420,7 +420,10 @@ export const layerSchemaErrorTransform = <Id, E extends ErrorConstraint, Require
   service: Context.Service<Id, HttpApiMiddleware<never, E, Requires>>,
   transform: (
     error: HttpApiSchemaError,
-    context: { readonly endpoint: HttpApiEndpoint.AnyWithProps; readonly group: HttpApiGroup.AnyWithProps }
+    context: {
+      readonly endpoint: HttpApiEndpoint.Top
+      readonly group: HttpApiGroup.Top
+    }
   ) => Effect.Effect<
     HttpServerResponse,
     ErrorSchemaFromConstraint<E>["Type"] | HttpApiSchemaError,

package/src/unstable/httpapi/HttpApiScalar.ts

@@ -151,7 +151,7 @@ type ScalarSource =
     readonly source: string
   }
 
-const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options: {
+const makeHandler = <Id extends string, Groups extends HttpApiGroup.Constraint>(options: {
   readonly api: HttpApi.HttpApi<Id, Groups>
   readonly source: ScalarSource
   readonly scalar: ScalarConfig | undefined
@@ -162,6 +162,15 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
     _integration: "html",
     ...scalar
   }
+  const scalarScript = options.source._tag === "Cdn"
+    ? `<script src="${
+      Html.escapeAttribute(
+        `https://cdn.jsdelivr.net/npm/@scalar/api-reference@${
+          encodeURIComponent(options.source.version ?? "latest")
+        }/dist/browser/standalone.min.js`
+      )
+    }" crossorigin></script>`
+    : `<script>${options.source.source}</script>`
   const response = HttpServerResponse.html(`<!doctype html>
 <html>
   <head>
@@ -170,12 +179,12 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
     ${
     !spec.info.description
       ? ""
-      : `<meta name="description" content="${Html.escape(spec.info.description)}"/>`
+      : `<meta name="description" content="${Html.escapeAttribute(spec.info.description)}"/>`
   }
     ${
     !spec.info.description
       ? ""
-      : `<meta name="og:description" content="${Html.escape(spec.info.description)}"/>`
+      : `<meta name="og:description" content="${Html.escapeAttribute(spec.info.description)}"/>`
   }
     <meta
       name="viewport"
@@ -183,13 +192,7 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
   </head>
   <body>
     <div id="api-reference-container"></div>
-    ${
-    options.source._tag === "Cdn"
-      ? `<script src="${`https://cdn.jsdelivr.net/npm/@scalar/api-reference@${
-        options.source.version ?? "latest"
-      }/dist/browser/standalone.min.js`}" crossorigin></script>`
-      : `<script>${options.source.source}</script>`
-  }
+    ${scalarScript}
     <script>
       window.Scalar.createApiReference(document.getElementById('api-reference-container'), {
         ...${Html.escapeJson(scalarConfig)},
@@ -215,7 +218,7 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
  * @category layers
  * @since 4.0.0
  */
-export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
+export const layer = <Id extends string, Groups extends HttpApiGroup.Constraint>(
   api: HttpApi.HttpApi<Id, Groups>,
   options?: {
     readonly path?: `/${string}` | undefined
@@ -246,7 +249,7 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
  * @category layers
  * @since 4.0.0
  */
-export const layerCdn = <Id extends string, Groups extends HttpApiGroup.Any>(
+export const layerCdn = <Id extends string, Groups extends HttpApiGroup.Constraint>(
   api: HttpApi.HttpApi<Id, Groups>,
   options?: {
     readonly path?: `/${string}` | undefined

package/src/unstable/httpapi/HttpApiSchema.ts

@@ -287,6 +287,14 @@ export type StreamSseMode = "events" | "data"
  * constructed from `data`, handlers and clients expose raw data values while
  * the server and client still use an SSE event schema internally.
  *
+ * **Gotchas**
+ *
+ * The client treats `effect/httpapi/stream/failure` as a stream failure only
+ * when its decoded `data` is a `Cause`. If an event schema accepts that name
+ * dynamically but decodes `data` to another value, the client emits it as an
+ * application event. Endpoint construction rejects event schemas that declare
+ * the reserved name statically.
+ *
  * @category models
  * @since 4.0.0
  */

package/src/unstable/httpapi/HttpApiSwagger.ts

@@ -18,7 +18,7 @@ import * as Html from "./internal/html.ts"
 import * as internal from "./internal/httpApiSwagger.ts"
 import * as OpenApi from "./OpenApi.ts"
 
-const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options: {
+const makeHandler = <Id extends string, Groups extends HttpApiGroup.Constraint>(options: {
   readonly api: HttpApi.HttpApi<Id, Groups>
 }) => {
   const spec = OpenApi.fromApi(options.api)
@@ -56,7 +56,7 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Any>(options
  * @category layers
  * @since 4.0.0
  */
-export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
+export const layer = <Id extends string, Groups extends HttpApiGroup.Constraint>(
   api: HttpApi.HttpApi<Id, Groups>,
   options?: {
     readonly path?: `/${string}` | undefined

package/src/unstable/httpapi/HttpApiTest.ts

@@ -21,7 +21,7 @@ import * as HttpRouter from "../http/HttpRouter.ts"
 import * as HttpServerRequest from "../http/HttpServerRequest.ts"
 import * as HttpServerResponse from "../http/HttpServerResponse.ts"
 import type * as HttpApi from "./HttpApi.ts"
-import type { Handlers } from "./HttpApiBuilder.ts"
+import type { HandlerRuntime } from "./HttpApiBuilder.ts"
 import * as HttpApiBuilder from "./HttpApiBuilder.ts"
 import * as HttpApiClient from "./HttpApiClient.ts"
 import type * as HttpApiEndpoint from "./HttpApiEndpoint.ts"
@@ -40,12 +40,12 @@ import type * as HttpApiGroup from "./HttpApiGroup.ts"
  */
 export const groups = Effect.fnUntraced(function*<
   ApiId extends string,
-  Groups extends HttpApiGroup.Any,
-  const Names extends ReadonlyArray<HttpApiGroup.Name<Groups>>,
-  SelectedGroups = HttpApiGroup.WithName<Groups, Names[number]>
+  Groups extends HttpApiGroup.Constraint,
+  const Identifiers extends ReadonlyArray<HttpApiGroup.Identifier<Groups>>,
+  SelectedGroups extends HttpApiGroup.Constraint = HttpApiGroup.WithIdentifier<Groups, Identifiers[number]>
 >(
   api: HttpApi.HttpApi<ApiId, Groups>,
-  groupNames: Names,
+  groupIdentifiers: Identifiers,
   options?: {
     readonly baseUrl?: string | URL | undefined
   }
@@ -63,22 +63,23 @@ export const groups = Effect.fnUntraced(function*<
 > {
   let context = yield* Effect.context<HttpApiGroup.ToService<ApiId, SelectedGroups>>()
 
-  for (const name in api.groups) {
-    const group = api.groups[name]
-    if (groupNames.includes(name as any)) {
+  const groups = api.groups as unknown as Record<string, HttpApiGroup.Top>
+  for (const identifier in groups) {
+    const group = groups[identifier]
+    if (groupIdentifiers.includes(identifier as any)) {
       continue
     }
-    const handlers = new Map<string, Handlers.Item<never>>()
+    const handlers = new Map<string, HandlerRuntime>()
     const routes: Array<HttpRouter.Route<any, any>> = []
-    for (const endpointName in group.endpoints) {
-      const endpoint = group.endpoints[endpointName]
-      const handler: Handlers.Item<never> = {
+    for (const endpointIdentifier in group.endpoints) {
+      const endpoint = group.endpoints[endpointIdentifier]
+      const handler: HandlerRuntime = {
         endpoint: endpoint as any,
-        handler: () => Effect.die(new Error(`Unhandled endpoint: ${endpointName}`)),
+        handler: () => Effect.die(new Error(`Unhandled endpoint: ${endpointIdentifier}`)),
         isRaw: false,
         uninterruptible: false
       }
-      handlers.set(endpointName, handler)
+      handlers.set(endpointIdentifier, handler)
       routes.push(HttpApiBuilder.handlerToRoute(group as any, handler, context))
     }
     context = Context.add(context, group as any, { handlers, routes })