shelving/api/Endpoint.d.ts

Toolkit for using data in JavaScript.

import type { Path } from "../util/path.js";
import { type Validator } from "../util/validate.js";
import type { EndpointCallback, EndpointHandler } from "./util.js";
/** Types for an HTTP request or response that does something. */
export type EndpointMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
/**
 * An abstract API resource definition, used to specify types for e.g. serverless functions.
 *
 * @param method The method of the resource, e.g. `GET`
 * @param path The path of the resource optionally including `{placeholder}` values, e.g. `/patient/{id}`
 * @param payload A `Validator` for the payload of the resource.
 * @param result A `Validator` for the result of the resource.
 */
export declare class Endpoint<P, R> {
    /** Endpoint method. */
    readonly method: EndpointMethod;
    /** Endpoint path, e.g. `/patient/{id}` */
    readonly path: Path;
    /** Payload validator. */
    readonly payload: Validator<P>;
    /** Result validator. */
    readonly result: Validator<R>;
    constructor(method: EndpointMethod, path: Path, payload: Validator<P>, result: Validator<R>);
    /**
     * Return an `EndpointHandler` for this endpoint.
     *
     * @param callback The callback function that implements the logic for this endpoint by receiving the payload and returning the response.
     */
    handler(callback: EndpointCallback<P, R>): EndpointHandler<P, R>;
    /**
     * Handle a request to this endpoint with a callback implementation, with a given payload and request.
     *
     * @param callback The endpoint callback function that implements the logic for this endpoint by receiving the payload and returning the response.
     * @param unsafePayload The payload to pass into the callback (will be validated against this endpoint's payload schema).
     * @param request The entire HTTP request that is being handled (payload was possibly extracted from this somehow).
     */
    handle(callback: EndpointCallback<P, R>, unsafePayload: unknown, request: Request): Promise<Response>;
    /** Convert to string, e.g. `GET /user/{id}` */
    toString(): string;
}
/** Extract the payload type from a `Endpoint`. */
export type PayloadType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<infer Y, unknown> ? Y : never;
/** Extract the result type from a `Endpoint`. */
export type EndpointType<X extends Endpoint<unknown, unknown>> = X extends Endpoint<unknown, infer Y> ? Y : never;
/**
 * Represent a GET request to a specified path, with validated payload and return types.
 * "The GET method requests a representation of the specified resource. Requests using GET should only retrieve data and should not contain a request content."
 */
export declare function GET<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
export declare function GET<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
export declare function GET<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
/**
 * Represent a POST request to a specified path, with validated payload and return types.
 * "The POST method submits an entity to the specified resource, often causing a change in state or side effects on the server.
 */
export declare function POST<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
export declare function POST<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
export declare function POST<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
/**
 * Represent a PUT request to a specified path, with validated payload and return types.
 * "The PUT method replaces all current representations of the target resource with the request content."
 */
export declare function PUT<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
export declare function PUT<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
export declare function PUT<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
/**
 * Represent a PATCH request to a specified path, with validated payload and return types.
 * "The PATCH method applies partial modifications to a resource."
 */
export declare function PATCH<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
export declare function PATCH<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
export declare function PATCH<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;
/**
 * Represent a DELETE request to a specified path, with validated payload and return types.
 * "The DELETE method deletes the specified resource."
 */
export declare function DELETE<P, R>(path: Path, payload?: Validator<P>, result?: Validator<R>): Endpoint<P, R>;
export declare function DELETE<P>(path: Path, payload: Validator<P>): Endpoint<P, undefined>;
export declare function DELETE<R>(path: Path, payload: undefined, result: Validator<R>): Endpoint<undefined, R>;