@h4ad/serverless-adapter
Version:
Run REST APIs and other web applications using your existing Node.js application framework (NestJS, Express, Koa, Hapi, Fastify and many others), on top of AWS, Azure, Digital Ocean and many other clouds.
279 lines (274 loc) • 8.92 kB
TypeScript
import { S as SingleValueHeaders, B as BothValueHeaders } from './headers-DjfGHDmI.js';
import * as http from 'http';
import { ServerResponse, IncomingMessage } from 'node:http';
import { I as ILogger } from './logger-F8qccesk.js';
declare const BODY: unique symbol;
declare const HEADERS: unique symbol;
/**
* The properties to create a {@link ServerlessResponse}.
*
* @breadcrumb Network / ServerlessResponse
* @public
*/
interface ServerlessResponseProps {
/**
* The HTTP Method from request
*/
method?: string;
}
/**
* The class that represents a response instance used to send to the framework and wait until the framework finishes processing the request.
* Once it's happens, we use the properties from this response to built the response to the cloud.
*
* @breadcrumb Network / ServerlessResponse
* @public
*/
declare class ServerlessResponse extends ServerResponse {
constructor({ method }: ServerlessResponseProps);
_header: string;
_headers?: Record<any, any>;
_wroteHeader?: boolean;
[BODY]: any[];
[HEADERS]: Record<any, any>;
get headers(): Record<any, any>;
static from(res: IncomingMessage): ServerlessResponse;
static body(res: ServerlessResponse): Buffer;
static headers(res: ServerlessResponse): http.OutgoingHttpHeaders & Record<any, any>;
setHeader(key: string, value: number | string | readonly string[]): any;
writeHead(statusCode: number, statusMessage?: string | any | any[], obj?: any | any[]): any;
/**
* I use ignore here because in nodejs 12.x, statusMessage can be string | OutgoingHttpHeaders
* But in nodejs \>=14.x, statusMessage can also be OutgoingHttpHeaders[]
* I take care of these cases above, but here I can't handle it well, so I give up
* nodejs 12.x ref: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/v12/http.d.ts#L229
* nodejs 14.x ref: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/node/v14/http.d.ts#L263
*/
protected callNativeWriteHead(statusCode: number, statusMessage?: string | any | any[], obj?: any | any[]): this;
}
/**
* The type that represents a resolver used to send the response, error or success, to the client
*
* @breadcrumb Contracts / ResolverContract
* @public
*/
type Resolver<TResponse, TReturn> = {
/**
* The method that will perform the task of forwarding the request to the framework and waiting for the promise to be resolved with the response
*
* @param task - The task to be executed
*/
run(task: () => Promise<TResponse>): TReturn;
};
/**
* The type that represents a delegate resolver that is passed to the adapter to handle what to do when an error occurs during forwarding.
*
* @breadcrumb Contracts / ResolverContract
* @public
*/
type DelegatedResolver<TResponse> = {
/**
* Send the success response to the client
*
* @param success - The serverless response
*/
succeed: (response: TResponse) => void;
/**
* Send the error response to the client
*
* @param error - The error object
*/
fail: (error: Error) => void;
};
/**
* The createResolver contract props
*
* @breadcrumb Contracts / ResolverContract
* @public
*/
type ResolverProps<TEvent, TContext, TCallback, TResponse> = {
/**
* The event sent by the serverless environment
*/
event: TEvent;
/**
* Indicates whether to forward the (error.stack) or not to the client
*/
respondWithErrors: boolean;
/**
* The instance of the logger
*/
log: ILogger;
/**
* The instance of the adapter
*/
adapter: AdapterContract<TEvent, TContext, TResponse>;
/**
* The context sent by serverless
*/
context?: TContext;
/**
* The callback sent by serverless
*/
callback?: TCallback;
};
/**
* The interface that represents the contract used to send the response to the client
*
* @breadcrumb Contracts / ResolverContract
* @public
*/
interface ResolverContract<TEvent, TContext, TCallback, TResponse, TReturn> {
/**
* Create the resolver based on the context, callback or promise
*
* @param props - The props used to create the resolver
*/
createResolver(props: ResolverProps<TEvent, TContext, TCallback, TResponse>): Resolver<TResponse, TReturn>;
}
/**
* The request interface used to bridge any event source to the framework.
*
* @breadcrumb Contracts / AdapterContract
* @public
*/
interface AdapterRequest {
/**
* The HTTP Method to use to create the request to the framework
*/
method: string;
/**
* The path to use to create the request to the framework
*/
path: string;
/**
* The headers to use to create the request to the framework
*/
headers: SingleValueHeaders;
/**
* The body as buffer to use to create the request to the framework
*/
body?: Buffer;
/**
* The remote address (client ip) to use to create the request to the framework
*/
remoteAddress?: string;
/**
* The address of the event source (used in Lambda\@edge)
*
* @deprecated It is no longer used in the library and will be removed in the next major release.
*/
host?: string;
/**
* The address of the event source (used in Lambda\@edge)
*
* @deprecated It is no longer used in the library and will be removed in the next major release.
*/
hostname?: string;
}
/**
* The props of the method that get the response from the framework and transform it into a format that the event source can handle
*
* @breadcrumb Contracts / AdapterContract
* @public
*/
interface GetResponseAdapterProps<TEvent> {
/**
* The event sent by the serverless
*/
event: TEvent;
/**
* The framework {@link ServerlessResponse | response}.
*
* @remarks It can be optional, as this method can be used when an error occurs during the handling of the request by the framework.
*/
response?: ServerlessResponse;
/**
* The framework response status code
*/
statusCode: number;
/**
* The framework response body
*/
body: string;
/**
* The framework response headers
*/
headers: BothValueHeaders;
/**
* Indicates whether the response is base64 encoded or not
*/
isBase64Encoded: boolean;
/**
* The instance of the logger
*/
log: ILogger;
}
/**
* The props of the method that handle the response when an error occurs while forwarding the request to the framework
*
* @breadcrumb Contracts / AdapterContract
* @public
*/
interface OnErrorProps<TEvent, TResponse> {
/**
* The event sent by the serverless
*/
event: TEvent;
/**
* The error throwed during forwarding
*/
error: Error;
/**
* The instance of the resolver
*/
delegatedResolver: DelegatedResolver<TResponse>;
/**
* Indicates whether to forward the (error.stack) or not to the client
*/
respondWithErrors: boolean;
/**
* The instance of the logger
*/
log: ILogger;
}
/**
* The interface that represents a contract between the adapter and the actual implementation of the adapter.
*
* @breadcrumb Contracts / AdapterContract
* @public
*/
interface AdapterContract<TEvent, TContext, TResponse> {
/**
* Get the adapter name
*/
getAdapterName(): string;
/**
* Decide if this adapter can handle a request based in the event payload
*
* @param event - The event sent by serverless
* @param context - The context sent by the serverless
* @param log - The instance of logger
*/
canHandle(event: unknown, context: TContext, log: ILogger): boolean;
/**
* Maps the serverless payload to an actual request that a framework can handle
*
* @param event - The event sent by serverless
* @param context - The context sent by the serverless
* @param log - The instance of logger
*/
getRequest(event: TEvent, context: TContext, log: ILogger): AdapterRequest;
/**
* Maps the response of the framework to a payload that serverless can handle
*
* @param props - The props sent by serverless
*/
getResponse(props: GetResponseAdapterProps<TEvent>): TResponse;
/**
* When an error occurs while forwarding the request to the framework
*
* @remarks You must call resolver.fail or resolver.succeed when implementing this method.
*/
onErrorWhileForwarding(props: OnErrorProps<TEvent, TResponse>): void;
}
export { type AdapterContract as A, type DelegatedResolver as D, type GetResponseAdapterProps as G, type OnErrorProps as O, type ResolverContract as R, ServerlessResponse as S, type AdapterRequest as a, type ResolverProps as b, type Resolver as c, type ServerlessResponseProps as d };