HttpApiEndpoint overview
Added in v1.0.0
Table of contents
- annotations
- constructors
- guards
- models
- HttpApiEndpoint (interface)
- HttpApiEndpoint (namespace)
- All (interface)
- Any (interface)
- ClientRequest (type alias)
- Context (type alias)
- Error (type alias)
- ErrorWithName (type alias)
- ExcludeName (type alias)
- ExcludeProvided (type alias)
- Handler (type alias)
- HandlerRedacted (type alias)
- HandlerRedactedWithName (type alias)
- HandlerResponse (type alias)
- HandlerResponseWithName (type alias)
- HandlerWithName (type alias)
- Headers (type alias)
- PathParsed (type alias)
- Payload (type alias)
- Request (type alias)
- Success (type alias)
- SuccessWithName (type alias)
- ValidateHeaders (type alias)
- ValidatePath (type alias)
- ValidatePayload (type alias)
- WithName (type alias)
- reflection
- request
- result
- type ids
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