HttpApiEndpoint overview
Added in v1.0.0
Table of contents
- constructors
- guards
- models
- HttpApiEndpoint (interface)
- HttpApiEndpoint (namespace)
- Any (interface)
- AnyWithProps (interface)
- AddContext (type alias)
- AddError (type alias)
- ClientRequest (type alias)
- Constructor (type alias)
- Context (type alias)
- ContextWithName (type alias)
- Error (type alias)
- ErrorContext (type alias)
- ErrorContextWithName (type alias)
- ErrorWithName (type alias)
- ExcludeName (type alias)
- ExcludeProvided (type alias)
- ExtractPath (type alias)
- Handler (type alias)
- HandlerResponse (type alias)
- HandlerResponseWithName (type alias)
- HandlerWithName (type alias)
- Headers (type alias)
- Name (type alias)
- PathEntries (type alias)
- PathParsed (type alias)
- Payload (type alias)
- Request (type alias)
- Success (type alias)
- SuccessWithName (type alias)
- UrlParams (type alias)
- ValidateHeaders (type alias)
- ValidateParams (type alias)
- ValidatePath (type alias)
- ValidatePayload (type alias)
- ValidateUrlParams (type alias)
- WithName (type alias)
- type ids
constructors
del
Signature
export declare const del: {
<const Name extends string>(name: Name): HttpApiEndpoint.Constructor<Name, "DELETE">
<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): HttpApiEndpoint.Constructor<Name, "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): HttpApiEndpoint.Constructor<Name, 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): HttpApiEndpoint.Constructor<Name, "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): HttpApiEndpoint.Constructor<Name, "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): HttpApiEndpoint.Constructor<Name, "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 UrlParams = never,
in out Payload = never,
in out Headers = never,
in out Success = void,
in out Error = never,
out R = never,
out RE = 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 urlParamsSchema: Option.Option<Schema.Schema<UrlParams, 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, RE>
readonly annotations: Context.Context<never>
readonly middlewares: ReadonlySet<HttpApiMiddleware.TagClassAny>
/**
* Add a schema for the success response of the endpoint. The status code
* will be inferred from the schema, otherwise it will default to 200.
*/
addSuccess<S extends Schema.Schema.Any>(
schema: S,
annotations?: {
readonly status?: number | undefined
}
): HttpApiEndpoint<
Name,
Method,
Path,
UrlParams,
Payload,
Headers,
Exclude<Success, void> | Schema.Schema.Type<S>,
Error,
R | Schema.Schema.Context<S>,
RE
>
/**
* Add an error response schema to the endpoint. The status code
* will be inferred from the schema, otherwise it will default to 500.
*/
addError<E extends Schema.Schema.Any>(
schema: E,
annotations?: {
readonly status?: number | undefined
}
): HttpApiEndpoint<
Name,
Method,
Path,
UrlParams,
Payload,
Headers,
Success,
Error | Schema.Schema.Type<E>,
R,
RE | Schema.Schema.Context<E>
>
/**
* 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.
*/
setPayload<P extends Schema.Schema.Any>(
schema: P & HttpApiEndpoint.ValidatePayload<Method, P>
): HttpApiEndpoint<
Name,
Method,
Path,
UrlParams,
Schema.Schema.Type<P>,
Headers,
Success,
Error,
R | Schema.Schema.Context<P>,
RE
>
/**
* 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.
*/
setPath<Path extends Schema.Schema.Any>(
schema: Path & HttpApiEndpoint.ValidatePath<Path>
): HttpApiEndpoint<
Name,
Method,
Schema.Schema.Type<Path>,
UrlParams,
Payload,
Headers,
Success,
Error,
R | Schema.Schema.Context<Path>,
RE
>
/**
* Set the schema for the url search parameters of the endpoint.
*/
setUrlParams<UrlParams extends Schema.Schema.Any>(
schema: UrlParams & HttpApiEndpoint.ValidateUrlParams<UrlParams>
): HttpApiEndpoint<
Name,
Method,
Path,
Schema.Schema.Type<UrlParams>,
Payload,
Headers,
Success,
Error,
R | Schema.Schema.Context<Path>,
RE
>
/**
* Set the schema for the headers of the endpoint. The schema will be
* used to validate the headers before the handler is called.
*/
setHeaders<H extends Schema.Schema.Any>(
schema: H & HttpApiEndpoint.ValidateHeaders<H>
): HttpApiEndpoint<
Name,
Method,
Path,
UrlParams,
Payload,
Schema.Schema.Type<H>,
Success,
Error,
R | Schema.Schema.Context<H>,
RE
>
/**
* Add a prefix to the path of the endpoint.
*/
prefix(
prefix: HttpRouter.PathInput
): HttpApiEndpoint<Name, Method, Path, UrlParams, Payload, Headers, Success, Error, R, RE>
/**
* Add an `HttpApiMiddleware` to the endpoint.
*/
middleware<I extends HttpApiMiddleware.HttpApiMiddleware.AnyId, S>(
middleware: Context.Tag<I, S>
): HttpApiEndpoint<
Name,
Method,
Path,
UrlParams,
Payload,
Headers,
Success,
Error | HttpApiMiddleware.HttpApiMiddleware.Error<I>,
R | I,
RE | HttpApiMiddleware.HttpApiMiddleware.ErrorContext<I>
>
/**
* Add an annotation on the endpoint.
*/
annotate<I, S>(
tag: Context.Tag<I, S>,
value: S
): HttpApiEndpoint<Name, Method, Path, UrlParams, Payload, Headers, Success, Error, R, RE>
/**
* Merge the annotations of the endpoint with the provided context.
*/
annotateContext<I>(
context: Context.Context<I>
): HttpApiEndpoint<Name, Method, Path, UrlParams, Payload, Headers, Success, Error, R, RE>
}
Added in v1.0.0
HttpApiEndpoint (namespace)
Added in v1.0.0
Any (interface)
Signature
export interface Any extends Pipeable {
readonly [TypeId]: TypeId
readonly name: string
}
Added in v1.0.0
AnyWithProps (interface)
Signature
export interface AnyWithProps extends HttpApiEndpoint<string, HttpMethod, any, any, any, any, any, any, any> {}
Added in v1.0.0
AddContext (type alias)
Signature
export type AddContext<Endpoint extends Any, R> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? HttpApiEndpoint<
_Name,
_Method,
_Path,
_UrlParams,
_Payload,
_Headers,
_Success,
_Error | HttpApiMiddleware.HttpApiMiddleware.Error<R>,
_R | R,
_RE | HttpApiMiddleware.HttpApiMiddleware.ErrorContext<R>
>
: never
Added in v1.0.0
AddError (type alias)
Signature
export type AddError<Endpoint extends Any, E, R> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? HttpApiEndpoint<_Name, _Method, _Path, _UrlParams, _Payload, _Headers, _Success, _Error | E, _R, _RE | R>
: never
Added in v1.0.0
ClientRequest (type alias)
Signature
export type ClientRequest<Path, UrlParams, Payload, Headers, WithResponse extends boolean> = ([Path] extends [void]
? {}
: { readonly path: Path }) &
([UrlParams] extends [never] ? {} : { readonly urlParams: UrlParams }) &
([Headers] extends [never] ? {} : { readonly headers: Headers }) &
([Payload] extends [never]
? {}
: Payload extends infer P
? P extends Brand<HttpApiSchema.MultipartTypeId>
? { readonly payload: FormData }
: { readonly payload: P }
: { readonly payload: Payload }) extends infer Req
? keyof Req extends never
? void | { readonly withResponse?: WithResponse }
: Req & { readonly withResponse?: WithResponse }
: void
Added in v1.0.0
Constructor (type alias)
Signature
export type Constructor<Name extends string, Method extends HttpMethod> = <
const Schemas extends ReadonlyArray<HttpApiSchema.AnyString>
>(
segments: TemplateStringsArray,
...schemas: ValidateParams<Schemas>
) => HttpApiEndpoint<
Name,
Method,
Schemas["length"] extends 0 ? never : Types.Simplify<ExtractPath<Schemas>>,
never,
never,
never,
void,
never,
Schemas[number]["Context"]
>
Added in v1.0.0
Context (type alias)
Signature
export type Context<Endpoint> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _R
: never
Added in v1.0.0
ContextWithName (type alias)
Signature
export type ContextWithName<Endpoints extends Any, Name extends string> = Context<WithName<Endpoints, Name>>
Added in v1.0.0
Error (type alias)
Signature
export type Error<Endpoint extends Any> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _Error
: never
Added in v1.0.0
ErrorContext (type alias)
Signature
export type ErrorContext<Endpoint> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _RE
: never
Added in v1.0.0
ErrorContextWithName (type alias)
Signature
export type ErrorContextWithName<Endpoints extends Any, Name extends string> = ErrorContext<WithName<Endpoints, Name>>
Added in v1.0.0
ErrorWithName (type alias)
Signature
export type ErrorWithName<Endpoints extends Any, Name extends string> = Error<WithName<Endpoints, Name>>
Added in v1.0.0
ExcludeName (type alias)
Signature
export type ExcludeName<Endpoints extends Any, Name extends string> = Exclude<Endpoints, { readonly name: Name }>
Added in v1.0.0
ExcludeProvided (type alias)
Signature
export type ExcludeProvided<Endpoints extends Any, Name extends string, R> = Exclude<
R,
| HttpRouter.HttpRouter.DefaultServices
| HttpRouter.HttpRouter.Provided
| HttpApiMiddleware.HttpApiMiddleware.ExtractProvides<ContextWithName<Endpoints, Name>>
>
Added in v1.0.0
ExtractPath (type alias)
Signature
export type ExtractPath<Schemas extends ReadonlyArray<HttpApiSchema.AnyString>> = {
readonly [Entry in PathEntries<Schemas> as Entry[0]]: Entry[1]["Type"]
}
Added in v1.0.0
Handler (type alias)
Signature
export type Handler<Endpoint extends Any, E, R> = (
request: Types.Simplify<Request<Endpoint>>
) => Effect<Success<Endpoint>, Error<Endpoint> | E, R>
Added in v1.0.0
HandlerResponse (type alias)
Signature
export type HandlerResponse<Endpoint extends Any, E, R> = (
request: Types.Simplify<Request<Endpoint>>
) => Effect<HttpServerResponse, Error<Endpoint> | E, R>
Added in v1.0.0
HandlerResponseWithName (type alias)
Signature
export type HandlerResponseWithName<Endpoints extends Any, 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 Any, 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 Any> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _Headers
: never
Added in v1.0.0
Name (type alias)
Signature
export type Name<Endpoint> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _Name
: never
Added in v1.0.0
PathEntries (type alias)
Signature
export type PathEntries<Schemas extends ReadonlyArray<HttpApiSchema.AnyString>> =
Extract<keyof Schemas, string> extends infer K
? K extends keyof Schemas
? Schemas[K] extends HttpApiSchema.Param<infer _Name, infer _S>
? [_Name, _S]
: Schemas[K] extends HttpApiSchema.AnyString
? [K, Schemas[K]]
: never
: never
: never
Added in v1.0.0
PathParsed (type alias)
Signature
export type PathParsed<Endpoint extends Any> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _Path
: never
Added in v1.0.0
Payload (type alias)
Signature
export type Payload<Endpoint extends Any> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _Payload
: never
Added in v1.0.0
Request (type alias)
Signature
export type Request<Endpoint extends Any> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? ([_Path] extends [never] ? {} : { readonly path: _Path }) &
([_UrlParams] extends [never] ? {} : { readonly urlParams: _UrlParams }) &
([_Payload] extends [never] ? {} : { readonly payload: _Payload }) &
([_Headers] extends [never] ? {} : { readonly headers: _Headers })
: {}
Added in v1.0.0
Success (type alias)
Signature
export type Success<Endpoint extends Any> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _Success
: never
Added in v1.0.0
SuccessWithName (type alias)
Signature
export type SuccessWithName<Endpoints extends Any, Name extends string> = Success<WithName<Endpoints, Name>>
Added in v1.0.0
UrlParams (type alias)
Signature
export type UrlParams<Endpoint extends Any> =
Endpoint extends HttpApiEndpoint<
infer _Name,
infer _Method,
infer _Path,
infer _UrlParams,
infer _Payload,
infer _Headers,
infer _Success,
infer _Error,
infer _R,
infer _RE
>
? _UrlParams
: never
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
ValidateParams (type alias)
Signature
export type ValidateParams<
Schemas extends ReadonlyArray<HttpApiSchema.AnyString>,
Prev extends HttpApiSchema.AnyString = never
> = Schemas extends [
infer Head extends HttpApiSchema.AnyString,
...infer Tail extends ReadonlyArray<HttpApiSchema.AnyString>
]
? [
Head extends HttpApiSchema.Param<infer _Name, infer _S>
? HttpApiSchema.Param<_Name, any> extends Prev
? `Duplicate param :${_Name}`
: Head
: Head,
...ValidateParams<Tail, Prev | Head>
]
: Schemas
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.Any> = 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
ValidateUrlParams (type alias)
Signature
export type ValidateUrlParams<S extends Schema.Schema.Any> =
S extends Schema.Schema<infer _A, infer _I, infer _R>
? [_I] extends [Readonly<Record<string, string | ReadonlyArray<string> | undefined>>]
? {}
: `UrlParams schema must be encodeable to strings`
: {}
Added in v1.0.0
WithName (type alias)
Signature
export type WithName<Endpoints extends Any, Name extends string> = Extract<Endpoints, { readonly name: 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