better-call 0.2.11 → 0.2.13-beta.1

package/dist/index.d.mts

@@ -0,0 +1,350 @@
+import { ZodSchema, ZodError } from 'zod';
+import { BufferSource } from 'stream/web';
+
+type Cookie = Record<string, string>;
+type SignedCookie = Record<string, string | false>;
+type PartitionCookieConstraint = {
+    partition: true;
+    secure: true;
+} | {
+    partition?: boolean;
+    secure?: boolean;
+};
+type SecureCookieConstraint = {
+    secure: true;
+};
+type HostCookieConstraint = {
+    secure: true;
+    path: "/";
+    domain?: undefined;
+};
+type CookieOptions = {
+    domain?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    maxAge?: number;
+    path?: string;
+    secure?: boolean;
+    signingSecret?: string;
+    sameSite?: "Strict" | "Lax" | "None" | "strict" | "lax" | "none";
+    partitioned?: boolean;
+    prefix?: CookiePrefixOptions;
+} & PartitionCookieConstraint;
+type CookiePrefixOptions = "host" | "secure";
+type CookieConstraint<Name> = Name extends `__Secure-${string}` ? CookieOptions & SecureCookieConstraint : Name extends `__Host-${string}` ? CookieOptions & HostCookieConstraint : CookieOptions;
+declare const parse: (cookie: string, name?: string) => Cookie;
+declare const parseSigned: (cookie: string, secret: string | BufferSource, name?: string) => Promise<SignedCookie>;
+declare const serialize: <Name extends string>(name: Name, value: string, opt?: CookieConstraint<Name>) => string;
+declare const serializeSigned: (name: string, value: string, secret: string | BufferSource, opt?: CookieOptions) => Promise<string>;
+
+/**
+ * Improve this type if possible
+ */
+type Input<T> = Prettify<{
+    [K in keyof T as T[K] extends never ? never : undefined extends T[K] ? never : K]: T[K];
+} & {
+    [K in keyof T as undefined extends T[K] ? K : never]?: T[K];
+}>;
+type RequiredKeysOf<BaseType extends object> = Exclude<{
+    [Key in keyof BaseType]: BaseType extends Record<Key, BaseType[Key]> ? Key : never;
+}[keyof BaseType], undefined>;
+type HasRequiredKeys<BaseType extends object> = RequiredKeysOf<BaseType> extends never ? false : true;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type IsEmptyObject<T> = keyof T extends never ? true : false;
+type UnionToIntersection<Union> = (Union extends unknown ? (distributedUnion: Union) => void : never) extends (mergedIntersection: infer Intersection) => void ? Intersection & Union : never;
+
+type Method = "GET" | "POST" | "PUT" | "DELETE" | "*";
+interface EndpointOptions {
+    /**
+     * Request Method
+     */
+    method: Method | Method[];
+    /**
+     * Body Schema
+     */
+    body?: ZodSchema;
+    /**
+     * Query Schema
+     */
+    query?: ZodSchema;
+    /**
+     * If true headers will be required to be passed in the context
+     */
+    requireHeaders?: boolean;
+    /**
+     * If true request object will be required
+     */
+    requireRequest?: boolean;
+    /**
+     * Endpoint metadata
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Middleware to use
+     */
+    use?: Endpoint[];
+}
+type InferBody<Options extends EndpointOptions> = Options["body"] extends ZodSchema<infer T> ? T : never;
+type InferQuery<Options extends EndpointOptions> = Options["query"] extends ZodSchema<infer T> ? T : never;
+type InferParamPath<Path> = Path extends `${infer _Start}:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof InferParamPath<Rest>]: string;
+} : Path extends `${infer _Start}:${infer Param}` ? {
+    [K in Param]: string;
+} : Path extends `${infer _Start}/${infer Rest}` ? InferParamPath<Rest> : {};
+type InferParamWildCard<Path> = Path extends `${infer _Start}/*:${infer Param}/${infer Rest}` | `${infer _Start}/**:${infer Param}/${infer Rest}` ? {
+    [K in Param | keyof InferParamPath<Rest>]: string;
+} : Path extends `${infer _Start}/*` ? {
+    [K in "_"]: string;
+} : Path extends `${infer _Start}/${infer Rest}` ? InferParamPath<Rest> : {};
+type InferParam<Path extends string> = IsEmptyObject<InferParamPath<Path> & InferParamWildCard<Path>> extends true ? never : Prettify<InferParamPath<Path> & InferParamWildCard<Path>>;
+type InferRequest<Option extends EndpointOptions> = Option["requireRequest"] extends true ? Request : Request | undefined;
+type InferHeaders<Option extends EndpointOptions> = Option["requireHeaders"] extends true ? Headers : Headers | undefined;
+type InferUse<Opts extends EndpointOptions["use"]> = Opts extends Endpoint[] ? UnionToIntersection<Awaited<ReturnType<Opts[number]>>> : never;
+type InferMethod<Options extends EndpointOptions> = Options["method"] extends Array<Method> ? Options["method"][number] : Options["method"];
+
+declare class APIError extends Error {
+    message: string;
+    status: number;
+    code: string;
+    headers: {};
+    constructor(message: string, status?: number, code?: string, headers?: {});
+}
+
+interface EndpointContext<Path extends string, Options extends EndpointOptions> {
+    /**
+     * JSON
+     *
+     * a helper function to create a JSON response with the correct headers
+     * and status code. If `asResponse` is set to true in the context then
+     * it will return a Response object instead of the JSON object.
+     *
+     * @param json - The JSON object to return
+     * @param routerResponse - The response object to return if `asResponse` is
+     * true in the context this will take precedence
+     */
+    json: <R extends Record<string, any>>(json: R, routerResponse?: {
+        status?: number;
+        headers?: Record<string, string>;
+        response?: Response;
+    } | Response) => Promise<R>;
+    /**
+     * Body
+     *
+     * The body object will be the parsed JSON from the request and validated
+     * against the body schema if it exists
+     */
+    body: InferBody<Options>;
+    /**
+     * Path
+     *
+     * The path of the endpoint
+     */
+    path: Path;
+    /**
+     * Method
+     */
+    method: InferMethod<Options>;
+    /**
+     * Query
+     *
+     * The query object will be the parsed query string from the request
+     * and validated against the query schema if it exists
+     */
+    query: InferQuery<Options>;
+    /**
+     * Params
+     *
+     * If the path is `/user/:id` and the request is `/user/1` then the params will
+     * be `{ id: "1" }` and if the path includes a wildcard like `/user/*` then the
+     * params will be `{ _: "1" }` where `_` is the wildcard key. If the wildcard
+     * is named like `/user/**:name` then the params will be `{ name: string }`
+     */
+    params: InferParam<Path>;
+    /**
+     * Request object
+     *
+     * If `requireRequest` is set to true in the endpoint options this will be
+     * required
+     */
+    request: InferRequest<Options>;
+    /**
+     * Headers
+     *
+     * If `requireHeaders` is set to true in the endpoint options this will be
+     * required
+     */
+    headers: InferHeaders<Options>;
+    /**
+     * Middleware context
+     */
+    context: InferUse<Options["use"]>;
+    /**
+     * Set header
+     *
+     * If it's called outside of a request it will just be ignored.
+     */
+    setHeader: (key: string, value: string) => void;
+    /**
+     * Get header
+     *
+     * If it's called outside of a request it will just return null
+     *
+     * @param key  - The key of the header
+     * @returns
+     */
+    getHeader: (key: string) => string | null;
+    /**
+     * cookie setter.
+     *
+     * If it's called outside of a request it will just be ignored.
+     */
+    setCookie: (key: string, value: string, options?: CookieOptions) => void;
+    /**
+     * Get cookie value
+     *
+     * If it's called outside of a request it will just be ignored.
+     */
+    getCookie: (key: string, prefix?: CookiePrefixOptions) => string | undefined;
+    /**
+     * Set signed cookie
+     */
+    setSignedCookie: (key: string, value: string, secret: string | BufferSource, options?: CookieOptions) => Promise<void>;
+    /**
+     * Get signed cookie value
+     */
+    getSignedCookie: (key: string, secret: string, prefix?: CookiePrefixOptions) => Promise<string | undefined | false>;
+    /**
+     * Redirect to url
+     */
+    redirect: (url: string) => APIError;
+}
+type Context<Path extends string, Options extends EndpointOptions> = Input<{
+    body: InferBody<Options>;
+    method?: InferMethod<Options>;
+    query: InferQuery<Options>;
+    params: InferParam<Path>;
+    request: InferRequest<Options>;
+    headers: InferHeaders<Options>;
+    asResponse?: boolean;
+}>;
+declare function createSetHeader(headers: Headers): (key: string, value: string) => void;
+declare function createGetHeader(headers: Headers): (key: string) => string | null;
+
+interface JSONResponse<R = any> {
+    /**
+     * Body of the response
+     * It'll be inferred as the response body.
+     * and on the server side this will be returned
+     * as a response of a handler.
+     */
+    body: R;
+    /**
+     * The actual response object
+     */
+    routerResponse: {
+        body?: Record<string, any>;
+        status?: number;
+        headers?: Record<string, string>;
+    };
+    /**
+     * Flag to identify the response type
+     */
+    _flag: "json";
+}
+type EndpointResponse = JSONResponse | Response | void | Record<string, any>;
+type InferResponse<Ctx, R> = Ctx extends {
+    asResponse: true;
+} ? Response : R extends JSONResponse<infer T> ? T : R;
+declare function createJSON({ asResponse, response, }: {
+    asResponse?: boolean;
+    response: Response;
+}): <R extends Record<string, any>>(json: R, routerResponse?: {
+    status?: number;
+    headers?: Record<string, string>;
+    response?: Response;
+}) => Promise<R | {
+    body: R;
+    routerResponse: {
+        status?: number;
+        headers?: Record<string, string>;
+        response?: Response;
+    } | undefined;
+    _flag: string;
+}>;
+type ValidationResponse = {
+    data: {
+        body: any;
+        query: any;
+    };
+    error: null;
+} | {
+    data: null;
+    error: {
+        message: string;
+    };
+};
+declare function runValidation(options: EndpointOptions, context: EndpointContext<any, any>): ValidationResponse;
+declare function fromError(error: ZodError): {
+    message: string;
+};
+
+declare const createEndpoint: <Path extends string, Options extends EndpointOptions, R extends EndpointResponse>(path: Path, options: Options, handler: (context: EndpointContext<Path, Options>) => Promise<R>) => {
+    <Ctx extends Context<Path, Options>>(...inputCtx: HasRequiredKeys<Ctx> extends true ? [Ctx] : [Ctx?]): Promise<Ctx["asResponse"] extends true ? Response : R>;
+    path: Path;
+    options: Options;
+};
+type Endpoint<Handler extends (ctx: any) => Promise<any> = (ctx: any) => Promise<any>, Options extends EndpointOptions = EndpointOptions> = {
+    path: string;
+    options: Options;
+} & Handler;
+
+interface RouterConfig {
+    /**
+     * Throw error if error occurred other than APIError
+     */
+    throwError?: boolean;
+    /**
+     * Handle error
+     */
+    onError?: (e: unknown) => void | Promise<void> | Response | Promise<Response>;
+    /**
+     * Base path for the router
+     */
+    basePath?: string;
+    /**
+     * Middlewares for the router
+     */
+    routerMiddleware?: {
+        path: string;
+        middleware: Endpoint;
+    }[];
+    /**
+     * On response interceptor
+     */
+    onResponse?: (res: Response) => any | Promise<any>;
+    /**
+     * On request interceptor
+     */
+    onRequest?: (req: Request) => any | Promise<any>;
+    /**
+     * Extra context to pass to the handler
+     */
+    extraContext?: Record<string, any>;
+}
+declare const createRouter: <E extends Record<string, Endpoint>, Config extends RouterConfig>(endpoints: E, config?: Config) => {
+    handler: (request: Request) => Promise<Response>;
+    endpoints: E;
+};
+
+type MiddlewareHandler<Options extends EndpointOptions, R extends EndpointResponse> = (context: EndpointContext<any, Options>) => Promise<R>;
+declare function createMiddleware<Opts extends EndpointOptions, R extends EndpointResponse>(optionsOrHandler: MiddlewareHandler<Opts, R>): Endpoint<MiddlewareHandler<Opts, R>, Opts>;
+declare function createMiddleware<Opts extends EndpointOptions, R extends EndpointResponse>(optionsOrHandler: Opts, handler: MiddlewareHandler<Opts, R>): Endpoint<MiddlewareHandler<Opts, R>, Opts>;
+
+declare const getCookie: (cookie: string, key: string, prefix?: CookiePrefixOptions) => string | undefined;
+declare const setCookie: (header: Headers, name: string, value: string, opt?: CookieOptions) => void;
+declare const setSignedCookie: (header: Headers, name: string, value: string, secret: string | BufferSource, opt?: CookieOptions) => Promise<void>;
+declare const getSignedCookie: (header: Headers, secret: string, key: string, prefix?: CookiePrefixOptions) => Promise<string | false | undefined>;
+
+export { type Context, type Cookie, type CookieConstraint, type CookieOptions, type CookiePrefixOptions, type Endpoint, type EndpointContext, type EndpointResponse, type HasRequiredKeys, type InferResponse, type Input, type IsEmptyObject, type JSONResponse, type Prettify, type RequiredKeysOf, type SignedCookie, type UnionToIntersection, createEndpoint, createGetHeader, createJSON, createMiddleware, createRouter, createSetHeader, fromError, getCookie, getSignedCookie, parse, parseSigned, runValidation, serialize, serializeSigned, setCookie, setSignedCookie };