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

HttpApiEndpoint overview

Added in v1.0.0


Table of contents


annotations

annotate

Add an annotation to the endpoint.

Signature

export declare const annotate: {
  <I, S>(tag: Context.Tag<I, S>, value: S): <A extends HttpApiEndpoint.All>(self: A) => A
  <A extends HttpApiEndpoint.All, I, S>(self: A, tag: Context.Tag<I, S>, value: S): A
}

Added in v1.0.0

annotateMerge

Merge the annotations of the endpoint with the provided context.

Signature

export declare const annotateMerge: {
  <I>(context: Context.Context<I>): <A extends HttpApiEndpoint.All>(self: A) => A
  <A extends HttpApiEndpoint.All, I>(self: A, context: Context.Context<I>): A
}

Added in v1.0.0

constructors

del

Signature

export declare const del: <const Name extends string>(
  name: Name,
  path: HttpRouter.PathInput
) => HttpApiEndpoint<Name, "DELETE">

Added in v1.0.0

get

Signature

export declare const get: <const Name extends string>(
  name: Name,
  path: HttpRouter.PathInput
) => HttpApiEndpoint<Name, "GET">

Added in v1.0.0

make

Signature

export declare const make: <Method extends HttpMethod>(
  method: Method
) => <const Name extends string>(name: Name, path: HttpRouter.PathInput) => HttpApiEndpoint<Name, Method>

Added in v1.0.0

patch

Signature

export declare const patch: <const Name extends string>(
  name: Name,
  path: HttpRouter.PathInput
) => HttpApiEndpoint<Name, "PATCH">

Added in v1.0.0

post

Signature

export declare const post: <const Name extends string>(
  name: Name,
  path: HttpRouter.PathInput
) => HttpApiEndpoint<Name, "POST">

Added in v1.0.0

put

Signature

export declare const put: <const Name extends string>(
  name: Name,
  path: HttpRouter.PathInput
) => HttpApiEndpoint<Name, "PUT">

Added in v1.0.0

guards

isHttpApiEndpoint

Signature

export declare const isHttpApiEndpoint: (u: unknown) => u is HttpApiEndpoint<any, any, any>

Added in v1.0.0

models

HttpApiEndpoint (interface)

Represents an API endpoint. An API endpoint is mapped to a single route on the underlying HttpRouter.

Signature

export interface HttpApiEndpoint<
  out Name extends string,
  out Method extends HttpMethod,
  in out Path = never,
  in out Payload = never,
  in out Headers = never,
  in out Success = void,
  in out Error = never,
  out R = never
> extends Pipeable {
  readonly [TypeId]: TypeId
  readonly name: Name
  readonly path: HttpRouter.PathInput
  readonly method: Method
  readonly pathSchema: Option.Option<Schema.Schema<Path, unknown, R>>
  readonly payloadSchema: Option.Option<Schema.Schema<Payload, unknown, R>>
  readonly headersSchema: Option.Option<Schema.Schema<Headers, unknown, R>>
  readonly successSchema: Schema.Schema<Success, unknown, R>
  readonly errorSchema: Schema.Schema<Error, unknown, R>
  readonly annotations: Context.Context<never>
}

Added in v1.0.0

HttpApiEndpoint (namespace)

Added in v1.0.0

All (interface)

Signature

export interface All extends Pipeable {
  readonly [TypeId]: TypeId
  readonly name: string
  readonly path: HttpRouter.PathInput
  readonly method: HttpMethod
  readonly pathSchema: Option.Option<Schema.Schema.All>
  readonly payloadSchema: Option.Option<Schema.Schema.All>
  readonly headersSchema: Option.Option<Schema.Schema.All>
  readonly successSchema: Schema.Schema.Any
  readonly errorSchema: Schema.Schema.All
  readonly annotations: Context.Context<never>
}

Added in v1.0.0

Any (interface)

Signature

export interface Any extends Pipeable {
  readonly [TypeId]: TypeId
  readonly name: string
  readonly path: HttpRouter.PathInput
  readonly method: HttpMethod
  readonly pathSchema: Option.Option<Schema.Schema.Any>
  readonly payloadSchema: Option.Option<Schema.Schema.Any>
  readonly headersSchema: Option.Option<Schema.Schema.Any>
  readonly successSchema: Schema.Schema.Any
  readonly errorSchema: Schema.Schema.Any
  readonly annotations: Context.Context<never>
}

Added in v1.0.0

ClientRequest (type alias)

Signature

export type ClientRequest<Path, Payload, Headers> = ([Path] extends [void] ? {} : { readonly path: Path }) &
  ([Headers] extends [never] ? {} : { readonly headers: Headers }) &
  ([Payload] extends [never]
    ? {}
    : [Payload] extends [Brand<HttpApiSchema.MultipartTypeId>]
      ? { readonly payload: FormData }
      : { readonly payload: Payload }) extends infer Req
  ? keyof Req extends never
    ? void
    : Req
  : void

Added in v1.0.0

Context (type alias)

Signature

export type Context<Endpoint> =
  Endpoint extends HttpApiEndpoint<
    infer _Name,
    infer _Method,
    infer _Path,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _R
  >
    ? _R
    : never

Added in v1.0.0

Error (type alias)

Signature

export type Error<Endpoint extends All> =
  Endpoint extends HttpApiEndpoint<
    infer _Name,
    infer _Method,
    infer _Path,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _R
  >
    ? _Error
    : never

Added in v1.0.0

ErrorWithName (type alias)

Signature

export type ErrorWithName<Endpoints extends All, Name extends string> = Error<WithName<Endpoints, Name>>

Added in v1.0.0

ExcludeName (type alias)

Signature

export type ExcludeName<Endpoints extends All, Name extends string> = Exclude<Endpoints, { readonly name: Name }>

Added in v1.0.0

ExcludeProvided (type alias)

Signature

export type ExcludeProvided<R> = Exclude<R, HttpRouter.HttpRouter.DefaultServices | HttpRouter.HttpRouter.Provided>

Added in v1.0.0

Handler (type alias)

Signature

export type Handler<Endpoint extends All, E, R> = (
  request: Types.Simplify<Request<Endpoint>>
) => Effect<Success<Endpoint>, E, R>

Added in v1.0.0

HandlerRedacted (type alias)

Signature

export type HandlerRedacted<Endpoint extends All, E, R> = (
  request: Types.Simplify<Request<Endpoint>>
) => Effect<readonly [Success<Endpoint>, Redacted], E, R>

Added in v1.0.0

HandlerRedactedWithName (type alias)

Signature

export type HandlerRedactedWithName<Endpoints extends All, Name extends string, E, R> = HandlerRedacted<
  WithName<Endpoints, Name>,
  E,
  R
>

Added in v1.0.0

HandlerResponse (type alias)

Signature

export type HandlerResponse<Endpoint extends All, E, R> = (
  request: Types.Simplify<Request<Endpoint>>
) => Effect<HttpServerResponse, E, R>

Added in v1.0.0

HandlerResponseWithName (type alias)

Signature

export type HandlerResponseWithName<Endpoints extends All, Name extends string, E, R> = HandlerResponse<
  WithName<Endpoints, Name>,
  E,
  R
>

Added in v1.0.0

HandlerWithName (type alias)

Signature

export type HandlerWithName<Endpoints extends All, Name extends string, E, R> = Handler<WithName<Endpoints, Name>, E, R>

Added in v1.0.0

Headers (type alias)

Signature

export type Headers<Endpoint extends All> =
  Endpoint extends HttpApiEndpoint<
    infer _Name,
    infer _Method,
    infer _Path,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _R
  >
    ? _Headers
    : never

Added in v1.0.0

PathParsed (type alias)

Signature

export type PathParsed<Endpoint extends All> =
  Endpoint extends HttpApiEndpoint<
    infer _Name,
    infer _Method,
    infer _Path,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _R
  >
    ? _Path
    : never

Added in v1.0.0

Payload (type alias)

Signature

export type Payload<Endpoint extends All> =
  Endpoint extends HttpApiEndpoint<
    infer _Name,
    infer _Method,
    infer _Path,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _R
  >
    ? _Payload
    : never

Added in v1.0.0

Request (type alias)

Signature

export type Request<Endpoint extends All> = {
  readonly path: PathParsed<Endpoint>
} & ([Payload<Endpoint>] extends [infer P] ? ([P] extends [never] ? {} : { readonly payload: P }) : {}) &
  ([Headers<Endpoint>] extends [infer H] ? ([H] extends [never] ? {} : { readonly headers: H }) : {})

Added in v1.0.0

Success (type alias)

Signature

export type Success<Endpoint extends All> =
  Endpoint extends HttpApiEndpoint<
    infer _Name,
    infer _Method,
    infer _Path,
    infer _Payload,
    infer _Headers,
    infer _Success,
    infer _Error,
    infer _R
  >
    ? _Success
    : never

Added in v1.0.0

SuccessWithName (type alias)

Signature

export type SuccessWithName<Endpoints extends All, Name extends string> = Success<WithName<Endpoints, Name>>

Added in v1.0.0

ValidateHeaders (type alias)

Signature

export type ValidateHeaders<S extends Schema.Schema.Any> =
  S extends Schema.Schema<infer _A, infer _I, infer _R>
    ? [_I] extends [Readonly<Record<string, string | undefined>>]
      ? {}
      : `Headers schema must be encodeable to strings`
    : {}

Added in v1.0.0

ValidatePath (type alias)

Signature

export type ValidatePath<S extends Schema.Schema.Any> =
  S extends Schema.Schema<infer _A, infer _I, infer _R>
    ? [_I] extends [Readonly<Record<string, string | undefined>>]
      ? {}
      : `Path schema must be encodeable to strings`
    : {}

Added in v1.0.0

ValidatePayload (type alias)

Signature

export type ValidatePayload<Method extends HttpMethod, P extends Schema.Schema.All> = Method extends HttpMethod.NoBody
  ? P extends Schema.Schema<infer _A, infer _I, infer _R>
    ? [_I] extends [Readonly<Record<string, string | ReadonlyArray<string> | undefined>>]
      ? {}
      : `'${Method}' payload must be encodeable to strings`
    : {}
  : {}

Added in v1.0.0

WithName (type alias)

Signature

export type WithName<Endpoints extends All, Name extends string> = Endpoints extends infer Endpoint
  ? Endpoint extends { readonly name: Name }
    ? Endpoint
    : never
  : never

Added in v1.0.0

reflection

schemaSuccess

Signature

export declare const schemaSuccess: <A extends HttpApiEndpoint.All>(
  self: A
) => Option.Option<Schema.Schema<HttpApiEndpoint.Success<A>, unknown, HttpApiEndpoint.Context<A>>>

Added in v1.0.0

request

prefix

Add a prefix to the path of the endpoint.

Signature

export declare const prefix: {
  (prefix: HttpRouter.PathInput): <A extends HttpApiEndpoint.All>(self: A) => A
  <A extends HttpApiEndpoint.All>(self: A, prefix: HttpRouter.PathInput): A
}

Added in v1.0.0

setHeaders

Set the schema for the headers of the endpoint. The schema will be used to validate the headers before the handler is called.

Signature

export declare const setHeaders: {
  <Method extends HttpMethod, H extends Schema.Schema.Any>(
    schema: H & HttpApiEndpoint.ValidateHeaders<H>
  ): <Name extends string, _Path, _P, _H, _S, _E, _R>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
  ) => HttpApiEndpoint<Name, Method, _Path, _P, Schema.Schema.Type<H>, _S, _E, _R | Schema.Schema.Context<H>>
  <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R, H extends Schema.Schema.Any>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>,
    schema: H & HttpApiEndpoint.ValidateHeaders<H>
  ): HttpApiEndpoint<Name, Method, _Path, _P, Schema.Schema.Type<H>, _S, _E, _R | Schema.Schema.Context<H>>
}

Added in v1.0.0

setPath

Set the schema for the path parameters of the endpoint. The schema will be used to validate the path parameters before the handler is called.

Signature

export declare const setPath: {
  <Path extends Schema.Schema.Any>(
    schema: Path & HttpApiEndpoint.ValidatePath<Path>
  ): <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
  ) => HttpApiEndpoint<Name, Method, Schema.Schema.Type<Path>, _P, _H, _S, _E, _R | Schema.Schema.Context<Path>>
  <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R, Path extends Schema.Schema.Any>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>,
    schema: Path & HttpApiEndpoint.ValidatePath<Path>
  ): HttpApiEndpoint<Name, Method, Schema.Schema.Type<Path>, _P, _H, _S, _E, _R | Schema.Schema.Context<Path>>
}

Added in v1.0.0

setPayload

Set the schema for the request body of the endpoint. The schema will be used to validate the request body before the handler is called.

For endpoints with no request body, the payload will use the url search parameters.

You can set a multipart schema to handle file uploads by using the HttpApiSchema.Multipart combinator.

Signature

export declare const setPayload: {
  <Method extends HttpMethod, P extends Schema.Schema.All>(
    schema: P & HttpApiEndpoint.ValidatePayload<Method, P>
  ): <Name extends string, _Path, _P, _H, _S, _E, _R>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
  ) => HttpApiEndpoint<Name, Method, _Path, Schema.Schema.Type<P>, _H, _S, _E, _R | Schema.Schema.Context<P>>
  <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R, P extends Schema.Schema.All>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>,
    schema: P & HttpApiEndpoint.ValidatePayload<Method, P>
  ): HttpApiEndpoint<Name, Method, _Path, Schema.Schema.Type<P>, _H, _S, _E, _R | Schema.Schema.Context<P>>
}

Added in v1.0.0

result

addError

Add an error response schema to the endpoint. The status code will be inferred from the schema, otherwise it will default to 500.

Signature

export declare const addError: {
  <E extends Schema.Schema.All>(
    schema: E,
    annotations?: { readonly status?: number | undefined }
  ): <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
  ) => HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E | Schema.Schema.Type<E>, _R | Schema.Schema.Context<E>>
  <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R, E extends Schema.Schema.All>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>,
    schema: E,
    annotations?: { readonly status?: number | undefined }
  ): HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E | Schema.Schema.Type<E>, _R | Schema.Schema.Context<E>>
}

Added in v1.0.0

setSuccess

Set the schema for the success response of the endpoint. The status code will be inferred from the schema, otherwise it will default to 200.

Signature

export declare const setSuccess: {
  <S extends Schema.Schema.Any>(
    schema: S,
    annotations?: { readonly status?: number | undefined }
  ): <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>
  ) => HttpApiEndpoint<Name, Method, _Path, _P, _H, Schema.Schema.Type<S>, _E, _R | Schema.Schema.Context<S>>
  <Name extends string, Method extends HttpMethod, _Path, _P, _H, _S, _E, _R, S extends Schema.Schema.Any>(
    self: HttpApiEndpoint<Name, Method, _Path, _P, _H, _S, _E, _R>,
    schema: S,
    annotations?: { readonly status?: number | undefined }
  ): HttpApiEndpoint<Name, Method, _Path, _P, _H, Schema.Schema.Type<S>, _E, _R | Schema.Schema.Context<S>>
}

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