Skip to content

HttpApiGroup.ts

HttpApiGroup.ts overview

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.

Since v4.0.0

Exports Grouped by Category

constructors
- make
guards
- isHttpApiGroup
models

constructors

make

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 name.

Signature

declare const make: <const Id extends string, const TopLevel extends boolean = false>(
  identifier: Id,
  options?: { readonly topLevel?: TopLevel | undefined }
) => HttpApiGroup<Id, never, TopLevel>

Since v4.0.0

guards

isHttpApiGroup

Returns true when a value is an HttpApiGroup, narrowing the value to the group interface.

Signature

declare const isHttpApiGroup: (u: unknown) => u is Any

Since v4.0.0

models

AddMiddleware (type alias)

Returns the type of a group after applying a middleware identifier to every endpoint in the group.

Signature

type AddMiddleware<Group, Id> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel>
    ? HttpApiGroup<_Name, HttpApiEndpoint.AddMiddleware<_Endpoints, Id>, _TopLevel>
    : never

Since v4.0.0

AddPrefix (type alias)

Returns the type of a group after adding the supplied path prefix to each endpoint in the group.

Signature

type AddPrefix<Group, Prefix> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel>
    ? HttpApiGroup<_Name, HttpApiEndpoint.AddPrefix<_Endpoints, Prefix>, _TopLevel>
    : never

Since v4.0.0

Any (interface)

A widened HttpApiGroup type used when the concrete group name, endpoints, and top-level flag are not needed.

Signature

export interface Any {
  readonly [TypeId]: typeof TypeId
  readonly identifier: string
  readonly key: string
  readonly endpoints: Record.ReadonlyRecord<string, HttpApiEndpoint.Any>
}

Since v4.0.0

AnyWithProps (type alias)

A widened group type that preserves concrete runtime properties such as identifier, key, top-level status, endpoints, and annotations.

Signature

type AnyWithProps = HttpApiGroup<string, HttpApiEndpoint.AnyWithProps, boolean>

Since v4.0.0

ApiGroup (interface)

Type-level identity for a group within an HTTP API, pairing the API id with the group name for service derivation.

Signature

export interface ApiGroup<ApiId extends string, Name extends string> {
  readonly _: unique symbol
  readonly apiId: ApiId
  readonly name: Name
}

Since v4.0.0

ClientServices (type alias)

Computes the schema encoding and decoding services required by clients for all endpoints in a group.

Signature

type ClientServices<Group> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel>
    ? HttpApiEndpoint.ClientServices<_Endpoints>
    : never

Since v4.0.0

Endpoints (type alias)

Extracts the endpoint union contained in an HttpApiGroup.

Signature

type Endpoints<Group> = Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel> ? _Endpoints : never

Since v4.0.0

EndpointsWithName (type alias)

Selects the endpoints in a group whose name matches the provided endpoint name.

Signature

type EndpointsWithName<Group, Name> = Endpoints<WithName<Group, Name>>

Since v4.0.0

ErrorServicesDecode (type alias)

Computes the services required to decode error responses for every endpoint in a group.

Signature

type ErrorServicesDecode<Group> = HttpApiEndpoint.ErrorServicesDecode<Endpoints<Group>>

Since v4.0.0

ErrorServicesEncode (type alias)

Computes the services required to encode error responses for every endpoint in a group.

Signature

type ErrorServicesEncode<Group> = HttpApiEndpoint.ErrorServicesEncode<Endpoints<Group>>

Since v4.0.0

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

export interface HttpApiGroup<
  out Id extends string,
  out Endpoints extends HttpApiEndpoint.Any = never,
  out TopLevel extends boolean = false
> extends Pipeable {
  new (_: never): {}
  readonly [TypeId]: typeof TypeId
  readonly identifier: Id
  readonly key: string
  readonly topLevel: TopLevel
  readonly endpoints: Record.ReadonlyRecord<string, Endpoints>
  readonly annotations: Context.Context<never>

  /**
   * Add an `HttpApiEndpoint` to an `HttpApiGroup`.
   */
  add<const A extends NonEmptyReadonlyArray<HttpApiEndpoint.Any>>(
    ...endpoints: A
  ): HttpApiGroup<Id, Endpoints | A[number], TopLevel>

  /**
   * Add a path prefix to all endpoints in an `HttpApiGroup`. Note that this will only
   * add the prefix to the endpoints before this api is called.
   */
  prefix<const Prefix extends PathInput>(
    prefix: Prefix
  ): HttpApiGroup<Id, HttpApiEndpoint.AddPrefix<Endpoints, Prefix>, TopLevel>

  /**
   * Adds an `HttpApiMiddleware` to every endpoint currently in the group.
   *
   * **Gotchas**
   *
   * Endpoints added after this method is called do not have the middleware
   * applied.
   */
  middleware<I extends HttpApiMiddleware.AnyId, S>(
    middleware: Context.Key<I, S>
  ): HttpApiGroup<Id, HttpApiEndpoint.AddMiddleware<Endpoints, I>, TopLevel>

  /**
   * Merge the annotations of an `HttpApiGroup` with the provided annotations.
   */
  annotateMerge<I>(annotations: Context.Context<I>): HttpApiGroup<Id, Endpoints, TopLevel>

  /**
   * Add an annotation to an `HttpApiGroup`.
   */
  annotate<I, S>(key: Context.Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>

  /**
   * Merges the provided context into every endpoint currently in the group.
   *
   * **Gotchas**
   *
   * Endpoints added after this method is called do not have these annotations.
   */
  annotateEndpointsMerge<I>(annotations: Context.Context<I>): HttpApiGroup<Id, Endpoints, TopLevel>

  /**
   * Adds an annotation to every endpoint currently in the group.
   *
   * **Gotchas**
   *
   * Endpoints added after this method is called do not have this annotation.
   */
  annotateEndpoints<I, S>(key: Context.Key<I, S>, value: S): HttpApiGroup<Id, Endpoints, TopLevel>
}

Since v4.0.0

MiddlewareClient (type alias)

Computes the client-side middleware services required by endpoints in a group.

Signature

type MiddlewareClient<Group> = HttpApiEndpoint.MiddlewareClient<Endpoints<Group>>

Since v4.0.0

MiddlewareError (type alias)

Computes the middleware error union for every endpoint in a group.

Signature

type MiddlewareError<Group> = HttpApiEndpoint.MiddlewareError<Endpoints<Group>>

Since v4.0.0

MiddlewareProvides (type alias)

Computes the services provided by middleware attached to any endpoint in a group.

Signature

type MiddlewareProvides<Group> = HttpApiEndpoint.MiddlewareProvides<Endpoints<Group>>

Since v4.0.0

MiddlewareServices (type alias)

Extracts the runtime services required by middleware attached to the endpoints in an HttpApiGroup.

Signature

type MiddlewareServices<Group> = HttpApiEndpoint.MiddlewareServices<Endpoints<Group>>

Since v4.0.0

Name (type alias)

Extracts the identifier literal from an HttpApiGroup.

Signature

type Name<Group> = Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _TopLevel> ? _Name : never

Since v4.0.0

ToService (type alias)

Derives the API-specific ApiGroup service identity for an HTTP API group.

Signature

type ToService<ApiId, A> =
  A extends HttpApiGroup<infer Name, infer _Endpoints, infer _TopLevel> ? ApiGroup<ApiId, Name> : never

Since v4.0.0

WithName (type alias)

Selects the group with the specified identifier from a union of groups.

Signature

type WithName<Group, Name> = Extract<Group, { readonly identifier: Name }>

Since v4.0.0