@alessiofrittoli/next-api/dist/types-BCw6mdsz.d.mts

Next.js API utility library

import { P as Page } from './page-DAsxsEeP.mjs';
import { ReadStream } from 'fs';
import { ReadableStream as ReadableStream$1 } from 'node:stream/web';
import { NextRequest } from 'next/server';
import { StreamGenerator } from '@alessiofrittoli/stream-reader/types';

/**
 * Namespace containing types related to API.
 */
declare namespace Api {
    /** The HTTP Request method. */
    type RequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
    /**
     * Namespace containing types related to CORS.
     */
    namespace CORS {
        /**
         * Represents the policy configuration for handling API requests.
         */
        interface Policy {
            /**
             * The Request allowed origin.
             * @remarks
             * This specifies the allowed origin(s) for the request. It can be a string, an array of strings, or null.
             */
            origin?: string | string[] | null;
            /**
             * An array of allowed Request Methods.
             * @remarks
             * This specifies the HTTP methods that are allowed for the request, excluding 'OPTIONS'.
             */
            methods?: Exclude<Api.RequestMethod, 'OPTIONS'>[];
            /**
             * An array of allowed Request Headers.
             * @remarks
             * This specifies the headers that are allowed in the request.
             */
            headers?: string[];
            /**
             * An array of exposed Response Headers.
             * @remarks
             * This specifies the headers that can be exposed in the response.
             */
            exposedHeaders?: string[];
            /**
             * Whether to allow credentials or not.
             * @remarks
             * This specifies whether credentials (such as cookies or HTTP authentication) are allowed in the request.
             */
            credentials?: boolean;
        }
    }
    /**
     * Namespace containing types related to API routes.
     */
    namespace Route {
        /**
         * Alias for {@link Page.Params} which share the same type.
         */
        type Params = Page.Params;
        /**
         * Represents the context for an API request.
         *
         * @template T The type of the parameters.
         */
        interface Context<T extends Api.Route.Params | undefined = Api.Route.Params> {
            /** Route parameters. */
            params: Promise<T>;
        }
        /**
         * Represents a Next.js API request with an optional generic type for extending the request object.
         *
         * @template T An optional type to extend the NextApiRequest object. Defaults to `unknown`.
         */
        type Request<T = unknown> = NextRequest & Partial<T>;
        /**
         * Represents the body of a request.
         *
         */
        interface RequestBody {
            /**
             * The Google reCaptcha v3 token.
             * reCaptcha is automatically verified in the API handler if the secret is defined in the ENV variables.
             * The request will be then processed if the token is found in the request body, otherwise it will be rejected.
             */
            gReCaptchaToken?: string;
            /**
             * User Requested locale.
             */
            locale?: string;
            [x: string]: any;
        }
        /** The JSON Response Type. */
        interface ResponseBody<T = unknown> {
            message: T;
        }
        /**
         * Represents the return type of an API handler function.
         * It can either be a `Response` object or a `Promise` that resolves to a `Response` object.
         */
        type Response = globalThis.Response | Promise<globalThis.Response>;
        /**
         * Represents an handler function that processes static API routes.
         *
         * @template Body The type of the request payload. Defaults to `unknown`.
         *
         * @param request The NextRequest object containing the payload of type `Body`.
         *
         * @returns A `Response` object or a `Promise` that resolves to a `Response` object.
         */
        type DefaultHandler<Body = unknown> = (request: Api.Route.Request<Body>) => Api.Route.Response;
        /**
         * Represents an handler function that processes dynamic or catch-all API routes.
         *
         * @template Body			The type of the request payload. Defaults to `unknown`.
         * @template RouteParams	The type of the route parameters available only in dynamic and catch-all routes. Defaults to `unknown`.
         *
         * @param request	The NextRequest object containing the payload of type `Body`.
         * @param ctx		The context object containing route parameters of type `RouteParams` available only in dynamic and catch-all routes.
         *
         * @returns A `Response` object or a `Promise` that resolves to a `Response` object.
         */
        type DynamicHandler<Body = unknown, RouteParams extends Api.Route.Params | undefined = Api.Route.Params> = (request: Api.Route.Request<Body>, ctx: Api.Route.Context<RouteParams>) => Api.Route.Response;
        /**
         * Represents an handler function that processes API routes.
         *
         * @template Body			The type of the request payload. Defaults to `unknown`.
         * @template RouteParams	The type of the route parameters available only in dynamic and catch-all routes. Defaults to `unknown`.
         *
         * @param request	The NextRequest object containing the payload of type `Body`.
         * @param ctx		The context object containing route parameters of type `RouteParams` available only in dynamic and catch-all routes.
         *
         * @returns A `Response` object or a `Promise` that resolves to a `Response` object.
         */
        type Handler<Body = unknown, RouteParams extends Api.Route.Params | undefined = undefined> = (RouteParams extends undefined ? Api.Route.DefaultHandler<Body> : Api.Route.DynamicHandler<Body, RouteParams>);
        /**
         * Represent the OPTIONS method API route that handles the CORS preflight request.
         *
         * @param request	The NextRequest object containing the payload of type `Body`.
         * @param ctx		The context object containing route parameters of type `RouteParams` available only in dynamic and catch-all routes.
         *
         * @returns A 204 `Response` object or a `Promise` that resolves to a `Response` object.
         */
        type CorsPreFlightHandler<Body = unknown, RouteParams extends Api.Route.Params | undefined = Api.Route.Params> = (request: Api.Route.Request<Body>, ctx: Api.Route.Context<RouteParams>, corsPolicy?: NextResponseProps['cors']) => Api.Route.Response;
    }
}

/**
 * Interface representing the options for the NextResponse constructor.
 *
 */
interface NextResponseProps {
    /** The Response BodyInit. */
    body?: ArrayBufferLike | BodyInit | null;
    /** ResponseInit */
    init?: ResponseInit;
    /** The NextRequest instance. This is used internally to retrieve Request Headers. */
    request?: NextRequest;
    /** An Object of {@link Api.CORS.Policy} defining custom policies for the API Response. If `true` CORS is enabled with the default configuration. */
    cors?: Api.CORS.Policy | true;
}
/**
 * Options for configuring CORS headers in an API response.
 */
interface CorsHeadersOptions {
    /** An object of {@link Api.CORS.Policy} defining custom policies for the API Response. */
    options?: Api.CORS.Policy & {
        requestOrigin?: string;
    };
    /** Custom Response Headers. */
    headers?: Headers | HeadersInit;
}
/**
 * Represents an iterator for a Next.js response stream.
 *
 * @template T - The type of data being streamed. Defaults to `unknown`.
 *
 * This type can be either a `ReadableStream` of type `T` or a `StreamGenerator` of type `T`.
 */
type NextResponseStreamInput<T = unknown> = (ReadStream | ReadableStream$1<T> | ReadableStream<T> | StreamGenerator<T>);

export { Api as A, type CorsHeadersOptions as C, type NextResponseProps as N, type NextResponseStreamInput as a };