@leanstacks/serverless-common/dist/index.d.ts

LeanStacks organization common serverless components.

import middy, { MiddlewareObj } from '@middy/core';
import * as aws_lambda from 'aws-lambda';
import { APIGatewayProxyEvent, APIGatewayProxyResult, Context, ScheduledEvent, APIGatewayProxyEventPathParameters, APIGatewayProxyEventQueryStringParameters, SNSEvent, SQSEvent, SQSBatchResponse } from 'aws-lambda';
import Joi, { ObjectSchema } from 'joi';
import { BatchWriteCommandInput, BatchWriteCommandOutput, DeleteCommandInput, DeleteCommandOutput, GetCommandInput, GetCommandOutput, PutCommandInput, PutCommandOutput, QueryCommandInput, QueryCommandOutput, ScanCommandInput, ScanCommandOutput, UpdateCommandInput, UpdateCommandOutput } from '@aws-sdk/lib-dynamodb';
import { SendMessageCommandInput, SendMessageCommandOutput } from '@aws-sdk/client-sqs';
import { AdminDisableUserCommandInput, AdminDisableUserCommandOutput, AdminSetUserPasswordCommandInput, AdminSetUserPasswordCommandOutput, ListUsersCommandInput, ListUsersCommandOutput } from '@aws-sdk/client-cognito-identity-provider';
import * as type_fest from 'type-fest';
import * as winston from 'winston';

/**
 * The `HttpError` class extends `Error` providing additional, standardized attributes
 * for AWS Lambda functions. The attributes include: `statusCode`.
 */
declare class HttpError extends Error {
    name: string;
    statusCode: number;
    constructor(messageOrError: string | Error, statusCode: number);
}

/**
 * The `ServiceError` class extends `Error` providing additional, standardized attributes
 * for AWS Lambda functions. The attributes include: `code` and `statusCode`.
 */
declare class ServiceError extends Error {
    name: string;
    code: number;
    statusCode: number;
    constructor(messageOrError: string | Error, code?: number, statusCode?: number);
}

/**
 * `BadRequestError` extends `HttpError` creating a specialized Error class for the
 * Bad Request (400) HTTP response code.
 * @see {@link HttpError}
 */
declare class BadRequestError extends HttpError {
    name: string;
    constructor(message?: string);
}

/**
 * `Forbidden` extends `HttpError` creating a specialized Error class for the
 * Forbidden (403) HTTP response code.
 * @see {@link HttpError}
 */
declare class ForbiddenError extends HttpError {
    name: string;
    constructor(message?: string);
}

/**
 * `NotFoundError` extends `HttpError` creating a specialized Error class for the
 * Not Found (404) HTTP response code.
 * @see {@link HttpError}
 */
declare class NotFoundError extends HttpError {
    name: string;
    constructor(message?: string);
}

/**
 * `HttpErrorHandlerOptions` provide configuration to the `http-error-handler`
 * middleware.
 */
type HttpErrorHandlerOptions = {
    defaultMessage?: string;
    defaultStatusCode?: number;
};
/**
 * Create middleware to process errors thrown from AWS Lambda handler functions.
 * @param [opts] - Optional. `HttpErrorHandlerOptions` configuration.
 * @returns Middleware to process errors thrown handler functions.
 */
declare const httpErrorHandler: (opts?: HttpErrorHandlerOptions) => MiddlewareObj<APIGatewayProxyEvent, APIGatewayProxyResult>;

/**
 * Initialize the Logger. Adds event metadata to each logged event.
 * @returns Middleware to initialize the Logger.
 */
declare const loggerInitializer: () => MiddlewareObj;

/**
 * ValidatorOptions
 */
type ValidatorOptions = {
    eventSchema?: Joi.ObjectSchema;
};
/**
 * Validate Lambda events with a Joi schema.
 * @param options - Options for the validator.
 * @returns Middleware to perform validation against a Joi schema.
 */
declare const validator: (options: ValidatorOptions) => MiddlewareObj;

/**
 * The `BaseConfig` type describes the configuration values supplied to every AWS Lambda
 * function by default. Extend `BaseConfig` with your own service-specific configuration
 * type.
 *
 * Example:
 * ```
 * type ServiceConfig = BaseConfig & {
 *   FOO: string;
 *   BAR: number;
 * }
 * ```
 */
type BaseConfig = {
    AWS_EXECUTION_ENV: string;
    AWS_LAMBDA_FUNCTION_NAME: string;
    AWS_LAMBDA_FUNCTION_MEMORY_SIZE: string;
    AWS_LAMBDA_FUNCTION_VERSION: string;
    AWS_REGION: string;
    LOGGING_ENABLED: boolean;
    LOGGING_LEVEL: string;
};
/**
 * Validates the configuration with the supplied Joi ObjectSchema. Uses `process.env` as the
 * configuration source.
 * @param schema - A `Joi.ObjectSchema` of type `TConfig` to validate the configuration values.
 * @returns An Object of type `TConfig` containing the validated configuration if successful,
 * otherwise throws a `ServiceError`.
 * @throws Throws a `ServiceError` when validation is unsuccessful.
 */
declare function validateConfig<TConfig>(schema: Joi.ObjectSchema<TConfig>): TConfig;
/**
 * A Joi ObjectSchema to validate the base AWS Lambda function configuration values.
 */
declare const baseConfigSchema: Joi.ObjectSchema<any>;
/**
 * A `BaseConfig` object containing the base AWS Lambda function configuration values.
 * This is useful when your function does not have additional configuration attributes.
 * @see {@link BaseConfig}
 */
declare const baseConfigValues: BaseConfig;
declare const ConfigService: {
    validateConfig: typeof validateConfig;
};

/**
 * A `DynamoClient` provides operations for accessing and mutating one or more Items
 * within an AWS DynamoDB Table.
 */
type DynamoClient = {
    batchWriteItems: (input: BatchWriteCommandInput) => Promise<BatchWriteCommandOutput>;
    deleteItem: (input: DeleteCommandInput) => Promise<DeleteCommandOutput>;
    getItem: (input: GetCommandInput) => Promise<GetCommandOutput>;
    putItem: (input: PutCommandInput) => Promise<PutCommandOutput>;
    queryItems: (input: QueryCommandInput) => Promise<QueryCommandOutput>;
    scanItems: (input: ScanCommandInput) => Promise<ScanCommandOutput>;
    updateItem: (input: UpdateCommandInput) => Promise<UpdateCommandOutput>;
};
/**
 * Use the `DynamoService` to access or mutate Items within an AWS DynamoDB Table.
 */
declare const DynamoService: DynamoClient;

/**
 * Use the `SQSService` to interact with AWS Simple Queue Service.
 * @see {@link https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/sqs/ | AWS SDK SQSClient}
 */
declare const SQSService: {
    sendMessage: (input: SendMessageCommandInput) => Promise<SendMessageCommandOutput>;
};

/**
 * The addresses to which the email should be sent.
 */
type EmailDestination = {
    to: string[];
    cc?: string[];
    bcc?: string[];
};
/**
 * An object containing data to populate the email template. The object keys
 * are strings and the values may be strings, numbers, or booleans.
 *
 * _Example:_
 * ```
 * {
 *   name: 'Joe Smith',
 *   age: 39,
 *   isEnabled: true
 * }
 * ```
 */
type EmailTemplateData = Record<string, string | number | boolean>;
/**
 * The `Email` type describes the request to send an email to one or more
 * recipients (i.e. destinations).
 */
type Email = {
    destinations: EmailDestination[];
    templateName: string;
    templateData?: EmailTemplateData;
};
/**
 * Use the `EmailService` to send an email message. Messages are sent
 * asynchronously.
 */
declare const EmailService: {
    send: (email: Email, queueUrl: string) => Promise<void>;
};

/**
 * Use the `CognitoIdentityProviderService` to interact with Amazon Cognito.
 * @see {@link https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/cognito-identity-provider/ | Amazon Cognito Identity Provider}
 */
declare const CognitoIdentityProviderService: {
    adminDisableUser: (input: AdminDisableUserCommandInput) => Promise<AdminDisableUserCommandOutput>;
    adminSetUserPassword: (input: AdminSetUserPasswordCommandInput) => Promise<AdminSetUserPasswordCommandOutput>;
    listUsers: (input: ListUsersCommandInput) => Promise<ListUsersCommandOutput>;
};

/**
 * The AWS Lambda handler function signature for API Gateway proxy events.
 */
type APIGatewayHandlerFn<TEvent = APIGatewayProxyEvent> = (event: TEvent, context: Context) => Promise<APIGatewayProxyResult>;
/**
 * The AWS Lambda handler function signature for Scheduled events
 * (e.g. cron events from AWS EventBridge).
 */
type ScheduledHandlerFn = (event: ScheduledEvent, context: Context) => Promise<void>;
/**
 * The AWS Lambda handler function signature for SNS events.
 */
type SNSHandlerFn = (event: SNSEvent, context: Context) => Promise<void>;
/**
 * The AWS Lambda handler function signature for SQS events.
 */
type SQSHandlerFn = (event: SQSEvent, context: Context) => Promise<SQSBatchResponse | void>;
/**
 * A Lambda function for invocation by another Lambda function.
 */
type LambdaEvent<TEvent = unknown> = TEvent;
/**
 * A Lambda function result for invocation by another Lambda function.
 */
type LambdaResult<TResult = unknown> = {
    status: number;
    statusText: string;
    data: TResult;
};
/**
 * The AWS Lambda handler function signature for Lambda events, i.e. Lambda to
 * Lambda function invocations.
 * Note: This is generally considered an anti-pattern. Search for another
 * design pattern before utilizing Lambda-to-Lambda.
 */
type LambdaHandler<TEvent = unknown, TResult = unknown> = (event: LambdaEvent<TEvent>, context: Context) => Promise<LambdaResult<TResult>>;
/**
 * Base options for `middyfy` functions.
 */
type MiddyfyOptions<THandler> = {
    handler: THandler;
};
/**
 * Options for middyfied API Gateway event handler functions.
 */
type APIGatewayMiddyfyOptions = MiddyfyOptions<APIGatewayHandlerFn> & {
    eventSchema?: ObjectSchema;
    defaultErrorMessage?: string;
    defaultErrorStatusCode?: number;
};
/**
 * Options for middyfied Scheduled event handler functions.
 */
type ScheduledMiddyfyOptions = MiddyfyOptions<ScheduledHandlerFn> & {
    eventSchema?: ObjectSchema;
};
/**
 * Options for middyfied SNS event handler functions.
 */
type SNSMiddyfyOptions = MiddyfyOptions<SNSHandlerFn> & {
    eventSchema?: ObjectSchema;
};
/**
 * Options for middyfied SQS event handler functions.
 */
type SQSMiddyfyOptions = MiddyfyOptions<SQSHandlerFn> & {
    eventSchema?: ObjectSchema;
};
/**
 * Options for middyfied Lambda event handler functions.
 */
type LambdaMiddyfyOptions<TEvent = unknown, TResult = unknown> = MiddyfyOptions<LambdaHandler<TEvent, TResult>> & {
    eventSchema?: ObjectSchema;
};
/**
 * Wraps an AWS Gateway proxy event handler function in middleware, returning the
 * AWS Lambda handler function.
 * @param options - The `APIGatewayMiddyfyOptions` object.
 * @returns A middyfied handler function.
 */
declare const middyfyAPIGateway: (options: APIGatewayMiddyfyOptions) => middy.MiddyfiedHandler<APIGatewayProxyEvent & Omit<APIGatewayProxyEvent, "body"> & {
    body: type_fest.JsonValue;
} & {
    multiValueQueryStringParameters: aws_lambda.APIGatewayProxyEventMultiValueQueryStringParameters;
    pathParameters: APIGatewayProxyEventPathParameters;
    queryStringParameters: APIGatewayProxyEventQueryStringParameters;
}, APIGatewayProxyResult, Error, Context>;
/**
 * Wraps a Scheduled event handler function in middleware, returning the
 * AWS Lambda handler function.
 * @param options - The `ScheduledMiddyfyOptions` object.
 * @returns A middyfied handler function.
 */
declare const middyfyScheduled: (options: ScheduledMiddyfyOptions) => middy.MiddyfiedHandler<ScheduledEvent<any>, void, Error, Context>;
/**
 * Wraps a SNS event handler function in middleware, returning the
 * AWS Lambda handler function.
 * @param options - The `SNSMiddyfyOptions` object.
 * @returns A middyfied handler function.
 */
declare const middyfySNS: (options: SNSMiddyfyOptions) => middy.MiddyfiedHandler<SNSEvent, void, Error, Context>;
/**
 * Wraps a SQS event handler function in middleware, returning the AWS Lambda
 * handler function.
 * @param options - The `SQSMiddyfyOptions` object.
 * @returns A middyfied handler function.
 */
declare const middyfySQS: (options: SQSMiddyfyOptions) => middy.MiddyfiedHandler<SQSEvent, void | SQSBatchResponse, Error, Context>;
/**
 * Wraps a Lambda event handler function in middleware, returning the AWS
 * Lambda handler function.
 * Note: Lambda-to-Lambda invocations are considered an anti-pattern. Search
 * for an alternative approach.
 * @param options - The `LambdaMiddyfyOptions` object.
 * @returns A middyfied handler function.
 * @see {@link https://docs.aws.amazon.com/lambda/latest/operatorguide/functions-calling-functions.html}
 */
declare const middyfyLambda: <TEvent, TResult>(options: LambdaMiddyfyOptions<TEvent, TResult>) => middy.MiddyfiedHandler<TEvent, LambdaResult<TResult>, Error, Context>;

/**
 * Utility functions for the creation and manipulation of identifier values.
 */
declare const ID: {
    generate: (length?: number) => string;
    ID_LENGTH_DEFAULT: number;
    ID_LENGTH_MAXIMUM: number;
    ID_LENGTH_MINIMUM: number;
};

declare const Logger: winston.Logger;

export { type APIGatewayHandlerFn, type APIGatewayMiddyfyOptions, BadRequestError, type BaseConfig, CognitoIdentityProviderService, ConfigService, DynamoService, type Email, type EmailDestination, EmailService, type EmailTemplateData, ForbiddenError, HttpError, type HttpErrorHandlerOptions, ID, type LambdaEvent, type LambdaHandler, type LambdaMiddyfyOptions, type LambdaResult, Logger, type MiddyfyOptions, NotFoundError, type SNSMiddyfyOptions, type SQSMiddyfyOptions, SQSService, type ScheduledHandlerFn, type ScheduledMiddyfyOptions, ServiceError, type ValidatorOptions, baseConfigSchema, baseConfigValues, httpErrorHandler, loggerInitializer, middyfyAPIGateway, middyfyLambda, middyfySNS, middyfySQS, middyfyScheduled, validator };