HttpApiGroup unstable
Defines named groups of HTTP API endpoints.
A group collects endpoints that belong to the same resource or feature area
inside an HttpApi. Builders, generated clients, URL builders, and OpenAPI
generation read the same group value, including its identifier, endpoints,
annotations, and topLevel flag. This module includes helpers for creating
groups, adding endpoints, prefixing paths, applying middleware, annotating
groups or endpoints, and deriving builder or client types.
Constructors
Creates an empty HttpApiGroup with the supplied identifier.
Details
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 identifier.
Signature
declare function make<Id extends string, TopLevel extends boolean = false>(identifier: Id, options?: { readonly topLevel?: TopLevel;}): HttpApiGroup<Id, never, TopLevel>Guards
isHttpApiGroup
unstableReturns true when a value is an HttpApiGroup, narrowing the value to the
group interface.
Signature
declare function isHttpApiGroup(u: unknown): u is TopModels
A widened HttpApiGroup type used when the concrete group identifier,
endpoints, and top-level flag are not needed.
Signature
interface Constraint { readonly "~effect/http-api/HttpApiGroup": "~effect/http-api/HttpApiGroup"; readonly endpoints: Record.ReadonlyRecord<string, HttpApiEndpoint.Constraint>; readonly identifier: string; readonly key: string;}An HttpApiGroup is a named collection of HttpApiEndpoints that represents
a portion of your domain.
Details
Endpoint implementations can be provided later with HttpApiBuilder.group.
Signature
interface HttpApiGroup<out Id extends string, in out Endpoints extends HttpApiEndpoint.Constraint = never, out TopLevel extends boolean = false> extends Pipeable { constructor(_: never); readonly "~effect/http-api/HttpApiGroup": "~effect/http-api/HttpApiGroup"; readonly annotations: Context<never>; readonly endpoints: EndpointMap<Endpoints>; readonly identifier: Id; readonly key: string; readonly topLevel: TopLevel; add<A extends readonly [Constraint, Constraint]>(...endpoints: A): HttpApiGroup<Id, Endpoints | A[number], TopLevel>; annotate<I, S>(key: Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>; annotateEndpoints<I, S>(key: Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>; annotateEndpointsMerge<I>(annotations: Context<I>): HttpApiGroup<Id, Endpoints, TopLevel>; annotateMerge<I>(annotations: Context<I>): HttpApiGroup<Id, Endpoints, TopLevel>; middleware<I extends AnyId, S>(middleware: Key<I, S>): HttpApiGroup<Id, AddMiddleware<Endpoints, I>, TopLevel>; prefix<Prefix extends PathInput>(prefix: Prefix): HttpApiGroup<Id, AddPrefix<Endpoints, Prefix>, TopLevel>;}A widened group type that preserves concrete runtime properties such as identifier, key, top-level status, endpoints, and annotations.
Signature
interface Top extends HttpApiGroup<string, HttpApiEndpoint.Top, boolean> { constructor(_: never);}Services
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.
Signature
interface Service<ApiId extends string, Identifier extends string> { readonly _: typeof _; readonly apiId: ApiId; readonly identifier: Identifier;}Utility Types
Returns the type of a group after applying a middleware identifier to every endpoint in the group.
Signature
type AddMiddleware<Group, Id extends HttpApiMiddleware.AnyId> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ? HttpApiGroup<_Identifier, HttpApiEndpoint.AddMiddleware<_Endpoints, Id>, _TopLevel> : neverReturns the type of a group after adding the supplied path prefix to each endpoint in the group.
Signature
type AddPrefix<Group, Prefix extends PathInput> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ? HttpApiGroup<_Identifier, HttpApiEndpoint.AddPrefix<_Endpoints, Prefix>, _TopLevel> : neverComputes the schema encoding and decoding services required by clients for all endpoints in a group.
Signature
type ClientServices<Group> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ? HttpApiEndpoint.ClientServices<_Endpoints> : neverExtracts the endpoint union contained in an HttpApiGroup.
Signature
type Endpoints<Group> = Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel> ? _Endpoints : neverExtracts the endpoint union from the group with the specified identifier.
Signature
type EndpointsWithIdentifier<Group extends Constraint, Identifier extends string> = Endpoints<WithIdentifier<Group, Identifier>>Computes the services required to decode error responses for every endpoint in a group.
Signature
type ErrorServicesDecode<Group> = HttpApiEndpoint.ErrorServicesDecode<Endpoints<Group>>Computes the services required to encode error responses for every endpoint in a group.
Signature
type ErrorServicesEncode<Group> = HttpApiEndpoint.ErrorServicesEncode<Endpoints<Group>>Extracts the identifier literal from an HttpApiGroup.
Signature
type Identifier<Group> = Group extends Constraint ? Group["identifier"] : neverComputes the client-side middleware services required by endpoints in a group.
Signature
type MiddlewareClient<Group> = HttpApiEndpoint.MiddlewareClient<Endpoints<Group>>Computes the middleware error union for every endpoint in a group.
Signature
type MiddlewareError<Group> = HttpApiEndpoint.MiddlewareError<Endpoints<Group>>Computes the services provided by middleware attached to any endpoint in a group.
Signature
type MiddlewareProvides<Group> = HttpApiEndpoint.MiddlewareProvides<Endpoints<Group>>Extracts the runtime services required by middleware attached to the endpoints in an HttpApiGroup.
Signature
type MiddlewareServices<Group> = HttpApiEndpoint.MiddlewareServices<Endpoints<Group>>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.
Signature
type ToService<ApiId extends string, Group extends Constraint> = Group extends Constraint ? Service<ApiId, Group["identifier"]> : neverSelects the group with the specified identifier from a union of groups.
Signature
type WithIdentifier<Group, Identifier extends string> = Extract<Group, { readonly identifier: Identifier;}>