Skip to main content Link Search Menu Expand Document (external link)

HttpApiGroup overview

Added in v1.0.0


Table of contents


constructors

make

An HttpApiGroup is a collection of HttpApiEndpoints. You can use an HttpApiGroup to represent a portion of your domain.

The endpoints can be implemented later using the HttpApiBuilder.group api.

Signature

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

Added in v1.0.0

guards

isHttpApiGroup

Signature

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

Added in v1.0.0

models

ApiGroup (interface)

Signature

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

Added in v1.0.0

HttpApiGroup (interface)

An HttpApiGroup is a collection of HttpApiEndpoints. You can use an HttpApiGroup to represent a portion of your domain.

The endpoints can be implemented later using the HttpApiBuilder.group api.

Signature

export interface HttpApiGroup<
  out Id extends string,
  out Endpoints extends HttpApiEndpoint.HttpApiEndpoint.Any = never,
  in out Error = HttpApiDecodeError,
  out R = never,
  out TopLevel extends true | false = false
> extends Pipeable {
  new (_: never): {}
  readonly [TypeId]: TypeId
  readonly identifier: Id
  readonly topLevel: TopLevel
  readonly endpoints: Record.ReadonlyRecord<string, Endpoints>
  readonly errorSchema: Schema.Schema<Error, unknown, R>
  readonly annotations: Context.Context<never>
  readonly middlewares: ReadonlySet<HttpApiMiddleware.TagClassAny>

  /**
   * Add an `HttpApiEndpoint` to an `HttpApiGroup`.
   */
  add<A extends HttpApiEndpoint.HttpApiEndpoint.Any>(endpoint: A): HttpApiGroup<Id, Endpoints | A, Error, R, TopLevel>

  /**
   * Add an error schema to an `HttpApiGroup`, which is shared by all endpoints in the
   * group.
   */
  addError<A, I, RX>(
    schema: Schema.Schema<A, I, RX>,
    annotations?: {
      readonly status?: number | undefined
    }
  ): HttpApiGroup<Id, Endpoints, Error | A, R | RX, 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(prefix: PathInput): HttpApiGroup<Id, Endpoints, Error, R, TopLevel>

  /**
   * Add an `HttpApiMiddleware` to the `HttpApiGroup`.
   *
   * It will be applied to all endpoints in the group.
   */
  middleware<I extends HttpApiMiddleware.HttpApiMiddleware.AnyId, S>(
    middleware: Context.Tag<I, S>
  ): HttpApiGroup<
    Id,
    Endpoints,
    Error | HttpApiMiddleware.HttpApiMiddleware.Error<I>,
    R | I | HttpApiMiddleware.HttpApiMiddleware.ErrorContext<I>,
    TopLevel
  >

  /**
   * Add an `HttpApiMiddleware` to each endpoint in the `HttpApiGroup`.
   *
   * Endpoints added after this api is called will not have the middleware
   * applied.
   */
  middlewareEndpoints<I extends HttpApiMiddleware.HttpApiMiddleware.AnyId, S>(
    middleware: Context.Tag<I, S>
  ): HttpApiGroup<Id, HttpApiEndpoint.HttpApiEndpoint.AddContext<Endpoints, I>, Error, R, TopLevel>

  /**
   * Merge the annotations of an `HttpApiGroup` with a new context.
   */
  annotateContext<I>(context: Context.Context<I>): HttpApiGroup<Id, Endpoints, Error, R, TopLevel>

  /**
   * Add an annotation to an `HttpApiGroup`.
   */
  annotate<I, S>(tag: Context.Tag<I, S>, value: S): HttpApiGroup<Id, Endpoints, Error, R, TopLevel>

  /**
   * For each endpoint in an `HttpApiGroup`, update the annotations with a new
   * context.
   *
   * Note that this will only update the annotations before this api is called.
   */
  annotateEndpointsContext<I>(context: Context.Context<I>): HttpApiGroup<Id, Endpoints, Error, R, TopLevel>

  /**
   * For each endpoint in an `HttpApiGroup`, add an annotation.
   *
   * Note that this will only add the annotation to the endpoints before this api
   * is called.
   */
  annotateEndpoints<I, S>(tag: Context.Tag<I, S>, value: S): HttpApiGroup<Id, Endpoints, Error, R, TopLevel>
}

Added in v1.0.0

HttpApiGroup (namespace)

Added in v1.0.0

Any (interface)

Signature

export interface Any {
  readonly [TypeId]: TypeId
  readonly identifier: string
}

Added in v1.0.0

AddContext (type alias)

Signature

export type AddContext<Group, R> = [R] extends [never]
  ? Group
  : Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _Error, infer _R, infer _TopLevel>
    ? HttpApiGroup<_Name, _Endpoints, _Error, _R | R, _TopLevel>
    : never

Added in v1.0.0

AnyWithProps (type alias)

Signature

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

Added in v1.0.0

ClientContext (type alias)

Signature

export type ClientContext<Group> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _Error, infer _R, infer _TopLevel>
    ?
        | _R
        | HttpApiEndpoint.HttpApiEndpoint.Context<_Endpoints>
        | HttpApiEndpoint.HttpApiEndpoint.ErrorContext<_Endpoints>
    : never

Added in v1.0.0

Context (type alias)

Signature

export type Context<Group> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _Error, infer _R, infer _TopLevel>
    ? HttpApiMiddleware.HttpApiMiddleware.Without<_R>
    : never

Added in v1.0.0

ContextWithName (type alias)

Signature

export type ContextWithName<Group extends Any, Name extends string> = Context<WithName<Group, Name>>

Added in v1.0.0

Endpoints (type alias)

Signature

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

Added in v1.0.0

EndpointsWithName (type alias)

Signature

export type EndpointsWithName<Group extends Any, Name extends string> = Endpoints<WithName<Group, Name>>

Added in v1.0.0

Error (type alias)

Signature

export type Error<Group> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _Error, infer _R, infer _TopLevel> ? _Error : never

Added in v1.0.0

ErrorContext (type alias)

Signature

export type ErrorContext<Group> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _Error, infer _R, infer _TopLevel>
    ? HttpApiMiddleware.HttpApiMiddleware.Without<_R> | HttpApiEndpoint.HttpApiEndpoint.ErrorContext<_Endpoints>
    : never

Added in v1.0.0

ErrorWithName (type alias)

Signature

export type ErrorWithName<Group extends Any, Name extends string> = Error<WithName<Group, Name>>

Added in v1.0.0

Middleware (type alias)

Signature

export type Middleware<Group> =
  Group extends HttpApiGroup<infer _Name, infer _Endpoints, infer _Error, infer _R, infer _TopLevel>
    ? HttpApiMiddleware.HttpApiMiddleware.Only<_R>
    : never

Added in v1.0.0

MiddlewareWithName (type alias)

Signature

export type MiddlewareWithName<Group extends Any, Name extends string> = Middleware<WithName<Group, Name>>

Added in v1.0.0

Name (type alias)

Signature

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

Added in v1.0.0

Provides (type alias)

Signature

export type Provides<Group extends Any> = HttpApiMiddleware.HttpApiMiddleware.ExtractProvides<Middleware<Group>>

Added in v1.0.0

ToService (type alias)

Signature

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

Added in v1.0.0

WithName (type alias)

Signature

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

Added in v1.0.0

type ids

TypeId

Signature

export declare const TypeId: typeof TypeId

Added in v1.0.0

TypeId (type alias)

Signature

export type TypeId = typeof TypeId

Added in v1.0.0