HttpApi.ts

HttpApi.ts overview

Describes an Effect HTTP API as groups of endpoints.

An HttpApi value is data: it has an identifier, annotations, and groups of endpoints that describe request inputs, responses, middleware, and route metadata. The same description can be used by server builders, generated clients, URL builders, OpenAPI generation, and reflection tools.

Since v4.0.0

constructors

make

Creates an empty HttpApi with the supplied identifier.

When to use

Use when you need to start defining an HTTP API, add groups with add or addHttpApi, provide endpoint implementations with HttpApiBuilder.group, and register the API with HttpApiBuilder.layer.

Signature

declare const make: <const Id extends string>(identifier: Id) => HttpApi<Id, never>

Source

Since v4.0.0

guards

isHttpApi

Returns true when a value is an HttpApi.

Signature

declare const isHttpApi: (u: unknown) => u is Top

Source

Since v4.0.0

models

Constraint (interface)

An HttpApi value with its identifier and group types erased.

Signature

export interface Constraint {
  readonly [TypeId]: typeof TypeId
}

Source

Since v4.0.0

HttpApi (interface)

An HttpApi is a collection of HTTP API groups and endpoints that represents a portion of your domain.

When to use

Use when endpoint implementations can be provided with HttpApiBuilder.group, and the completed API can be registered with HttpApiBuilder.layer.

Signature

export interface HttpApi<
  out Id extends string,
  in out Groups extends HttpApiGroup.Constraint = never
> extends Pipeable {
  new (_: never): {}
  readonly [TypeId]: typeof TypeId
  readonly identifier: Id
  readonly groups: GroupMap<Groups>
  readonly annotations: Context.Context<never>

  /**
   * Add a `HttpApiGroup` to the `HttpApi`.
   */
  add<const A extends NonEmptyReadonlyArray<HttpApiGroup.Constraint>>(...groups: A): HttpApi<Id, Groups | A[number]>

  /**
   * Adds every group from another `HttpApi` while preserving its annotation scope.
   *
   * **When to use**
   *
   * Use when you want to compose an API from groups declared and annotated under another API.
   *
   * **Details**
   *
   * The added API is flattened into this API rather than retained as a nested value. Each added group
   * is copied with the added API's annotations, leaving the added API unchanged. Annotation precedence
   * from least to most specific is this API, the added API, the group, and then the endpoint.
   *
   * **Gotchas**
   *
   * Annotations from the added API do not become top-level annotations of the result and do not affect
   * groups already present in this API. They remain scoped to the groups and endpoints being added.
   */
  addHttpApi<Id2 extends string, Groups2 extends HttpApiGroup.Constraint>(
    api: HttpApi<Id2, Groups2>
  ): HttpApi<Id, Groups | Groups2>

  /**
   * Prefix all endpoints in the `HttpApi`.
   */
  prefix<const Prefix extends PathInput>(prefix: Prefix): HttpApi<Id, HttpApiGroup.AddPrefix<Groups, Prefix>>

  /**
   * Adds a middleware to every endpoint currently in the `HttpApi`.
   *
   * **Gotchas**
   *
   * Endpoints added after this method is called do not receive the middleware.
   */
  middleware<I extends HttpApiMiddleware.AnyId, S>(
    middleware: Context.Key<I, S>
  ): HttpApi<Id, HttpApiGroup.AddMiddleware<Groups, I>>

  /**
   * Annotate the `HttpApi`.
   */
  annotate<I, S>(tag: Context.Key<I, S>, value: S): HttpApi<Id, Groups>

  /**
   * Annotate the `HttpApi` with a Context.
   */
  annotateMerge<I>(context: Context.Context<I>): HttpApi<Id, Groups>
}

Source

Since v4.0.0

Top (interface)

An HttpApi with broad identifier and group types while retaining the concrete runtime properties used by implementation helpers.

Signature

export interface Top extends HttpApi<string, HttpApiGroup.Top> {}

Source

Since v4.0.0

reflection

reflect

Describes the groups and endpoints in an HttpApi.

Details

The callbacks receive each group or endpoint with merged annotations, endpoint middleware, and response schemas grouped by HTTP status.

Signature

declare const reflect: <Id extends string, Groups extends HttpApiGroup.Constraint>(
  self: HttpApi<Id, Groups>,
  options: {
    readonly predicate?:
      | Predicate.Predicate<{ readonly endpoint: HttpApiEndpoint.Top; readonly group: HttpApiGroup.Top }>
      | undefined
    readonly onGroup: (options: {
      readonly group: HttpApiGroup.Top
      readonly mergedAnnotations: Context.Context<never>
    }) => void
    readonly onEndpoint: (options: {
      readonly group: HttpApiGroup.Top
      readonly endpoint: HttpApiEndpoint.Top
      readonly mergedAnnotations: Context.Context<never>
      readonly middleware: ReadonlySet<HttpApiMiddleware.AnyService>
      readonly successes: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
      readonly errors: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
    }) => void
  }
) => void

Source

Since v4.0.0

services

AdditionalSchemas (class)

Adds additional schemas to components/schemas. The provided schemas must have a identifier annotation.

Signature

declare class AdditionalSchemas

Source

Since v4.0.0