HttpApiGroup
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
Guards
isHttpApiGroup
Returns true when a value is an HttpApiGroup, narrowing the value to the group interface.
Signature
declare function isHttpApiGroup(u: unknown): u is Top;Models
Constraint interface
A widened HttpApiGroup type used when the concrete group identifier, endpoints, and top-level flag are not needed.
Signature
interface Constraint {
readonly "~effect/httpapi/HttpApiGroup": "~effect/httpapi/HttpApiGroup";
readonly endpoints: Record.ReadonlyRecord<string, HttpApiEndpoint.Constraint>;
readonly identifier: string;
readonly key: string;
}HttpApiGroup interface
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/httpapi/HttpApiGroup": "~effect/httpapi/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
AddMiddleware type
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>
: never;Returns 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>
: never;ClientServices type
Computes 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>
: never;Extracts the endpoint union contained in an HttpApiGroup.
Signature
type Endpoints<Group> =
Group extends HttpApiGroup<infer _Identifier, infer _Endpoints, infer _TopLevel>
? _Endpoints
: never;EndpointsWithIdentifier type
Extracts the endpoint union from the group with the specified identifier.
Signature
type EndpointsWithIdentifier<Group extends Constraint, Identifier extends string> = Endpoints<
WithIdentifier<Group, Identifier>
>;ErrorServicesDecode type
Computes the services required to decode error responses for every endpoint in a group.
Signature
type ErrorServicesDecode<Group> = HttpApiEndpoint.ErrorServicesDecode<Endpoints<Group>>;ErrorServicesEncode type
Computes the services required to encode error responses for every endpoint in a group.
Signature
type ErrorServicesEncode<Group> = HttpApiEndpoint.ErrorServicesEncode<Endpoints<Group>>;Identifier type
Extracts the identifier literal from an HttpApiGroup.
Signature
type Identifier<Group> = Group extends Constraint ? Group["identifier"] : never;MiddlewareClient type
Computes the client-side middleware services required by endpoints in a group.
Signature
type MiddlewareClient<Group> = HttpApiEndpoint.MiddlewareClient<Endpoints<Group>>;MiddlewareError type
Computes the middleware error union for every endpoint in a group.
Signature
type MiddlewareError<Group> = HttpApiEndpoint.MiddlewareError<Endpoints<Group>>;MiddlewareProvides type
Computes the services provided by middleware attached to any endpoint in a group.
Signature
type MiddlewareProvides<Group> = HttpApiEndpoint.MiddlewareProvides<Endpoints<Group>>;MiddlewareServices type
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"]>
: never;WithIdentifier type
Selects the group with the specified identifier from a union of groups.
Signature
type WithIdentifier<Group, Identifier extends string> = Extract<
Group,
{
readonly identifier: Identifier;
}
>;
Creates an empty
HttpApiGroupwith the supplied identifier.Details
Add endpoints with
add, provide implementations withHttpApiBuilder.group, and settopLevelwhen the generated client should expose endpoint methods directly instead of nesting them under the group identifier.