@h4ad/serverless-adapter 1.0.1

package/lib/resolvers/aws-context.resolver.js

@@ -0,0 +1,55 @@
+"use strict";
+//#region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AwsContextResolver = void 0;
+//#endregion
+/**
+ * The class that implements the resolver by using the AWS Context object.
+ *
+ * @note To use this resolver, you MUST leave `{@link https://docs.aws.amazon.com/lambda/latest/dg/nodejs-context.html callbackWaitsForEmptyEventLoop}` as true, otherwise, AWS will not wait for this resolver to resolve.
+ *
+ * ```md
+ * From the AWS Documentation, describing the functions used in this resolver:
+ * // Functions for compatibility with earlier Node.js Runtime v0.10.42
+ * // No longer documented, so they are deprecated, but they still work
+ * // as of the 12.x runtime, so they are not removed from the types.
+ * ```
+ * @deprecated
+ */
+class AwsContextResolver {
+    /**
+     * @inheritDoc
+     */
+    createResolver({ context, event, log, respondWithErrors, adapter, }) {
+        if (!context) {
+            throw new Error('Could not figure out how to create the resolver because the "context" argument was not sent.');
+        }
+        if (!context.succeed) {
+            throw new Error('Could not figure out how to create the resolver because the "context" argument didn\'t have the "succeed" function.');
+        }
+        if (!context.fail) {
+            throw new Error('Could not figure out how to create the resolver because the "context" argument didn\'t have the "fail" function.');
+        }
+        const delegatedResolver = {
+            succeed: response => context.succeed(response),
+            fail: error => context.fail(error),
+        };
+        return {
+            run: task => {
+                task()
+                    .then(response => delegatedResolver.succeed(response))
+                    .catch(error => {
+                    log.error('SERVERLESS_ADAPTER:RESPOND_TO_EVENT_SOURCE_WITH_ERROR', error);
+                    adapter.onErrorWhileForwarding({
+                        delegatedResolver,
+                        error,
+                        log,
+                        event,
+                        respondWithErrors,
+                    });
+                });
+            },
+        };
+    }
+}
+exports.AwsContextResolver = AwsContextResolver;

package/lib/resolvers/callback.resolver.d.ts

@@ -0,0 +1,16 @@
+import { Resolver, ResolverContract, ResolverProps } from '../contracts';
+/**
+ * The default signature of the callback sent by serverless
+ */
+export declare type ServerlessCallback<TResponse> = (error: Error | null, success: TResponse | null) => void;
+/**
+ * The class that implements the resolver using the callback function sent by serverless
+ *
+ * @note To use this resolver on AWS, you MUST leave `{@link https://docs.aws.amazon.com/lambda/latest/dg/nodejs-context.html callbackWaitsForEmptyEventLoop}` as true, otherwise, AWS will not wait for this resolver to resolve.
+ */
+export declare class CallbackResolver<TEvent, TContext, TResponse> implements ResolverContract<TEvent, TContext, ServerlessCallback<any>, TResponse, void> {
+    /**
+     * @inheritDoc
+     */
+    createResolver({ callback, event, log, respondWithErrors, adapter, }: ResolverProps<TEvent, TContext, ServerlessCallback<any>, TResponse>): Resolver<any, void>;
+}

package/lib/resolvers/callback.resolver.js

@@ -0,0 +1,40 @@
+"use strict";
+//#region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallbackResolver = void 0;
+/**
+ * The class that implements the resolver using the callback function sent by serverless
+ *
+ * @note To use this resolver on AWS, you MUST leave `{@link https://docs.aws.amazon.com/lambda/latest/dg/nodejs-context.html callbackWaitsForEmptyEventLoop}` as true, otherwise, AWS will not wait for this resolver to resolve.
+ */
+class CallbackResolver {
+    /**
+     * @inheritDoc
+     */
+    createResolver({ callback, event, log, respondWithErrors, adapter, }) {
+        if (!callback) {
+            throw new Error('Could not figure out how to create the resolver because the "callback" argument was not sent.');
+        }
+        const delegatedResolver = {
+            succeed: response => callback(null, response),
+            fail: error => callback(error, null),
+        };
+        return {
+            run: task => {
+                task()
+                    .then(response => delegatedResolver.succeed(response))
+                    .catch(error => {
+                    log.error('SERVERLESS_ADAPTER:RESPOND_TO_EVENT_SOURCE_WITH_ERROR', error);
+                    adapter.onErrorWhileForwarding({
+                        delegatedResolver,
+                        error,
+                        log,
+                        event,
+                        respondWithErrors,
+                    });
+                });
+            },
+        };
+    }
+}
+exports.CallbackResolver = CallbackResolver;

package/lib/resolvers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './aws-context.resolver';
+export * from './callback.resolver';
+export * from './promise.resolver';

package/lib/resolvers/index.js

@@ -0,0 +1,15 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./aws-context.resolver"), exports);
+__exportStar(require("./callback.resolver"), exports);
+__exportStar(require("./promise.resolver"), exports);

package/lib/resolvers/promise.resolver.d.ts

@@ -0,0 +1,10 @@
+import { Resolver, ResolverContract, ResolverProps } from '../contracts';
+/**
+ * The class that implements the resolver using the promise object sent by this library
+ */
+export declare class PromiseResolver<TEvent, TContext, TCallback, TResponse, TReturn> implements ResolverContract<TEvent, TContext, TCallback, TResponse, Promise<any>> {
+    /**
+     * @inheritDoc
+     */
+    createResolver({ event, log, respondWithErrors, adapter, }: ResolverProps<TEvent, TContext, TCallback, TResponse>): Resolver<TResponse, Promise<TReturn>>;
+}

package/lib/resolvers/promise.resolver.js

@@ -0,0 +1,38 @@
+"use strict";
+//#region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromiseResolver = void 0;
+//#endregion
+/**
+ * The class that implements the resolver using the promise object sent by this library
+ */
+class PromiseResolver {
+    /**
+     * @inheritDoc
+     */
+    createResolver({ event, log, respondWithErrors, adapter, }) {
+        return {
+            run: task => {
+                return new Promise((resolve, reject) => {
+                    const delegatedResolver = {
+                        succeed: response => resolve(response),
+                        fail: error => reject(error),
+                    };
+                    task()
+                        .then(response => delegatedResolver.succeed(response))
+                        .catch(error => {
+                        log.error('SERVERLESS_ADAPTER:RESPOND_TO_EVENT_SOURCE_WITH_ERROR', error);
+                        adapter.onErrorWhileForwarding({
+                            delegatedResolver,
+                            error,
+                            log,
+                            event,
+                            respondWithErrors,
+                        });
+                    });
+                });
+            },
+        };
+    }
+}
+exports.PromiseResolver = PromiseResolver;

package/lib/serverless-adapter.d.ts

@@ -0,0 +1,114 @@
+import { BinarySettings } from './@types';
+import { AdapterContract, FrameworkContract, HandlerContract, ResolverContract, ServerlessHandler } from './contracts';
+import { ILogger } from './core';
+/**
+ * The class used to build the serverless handler.
+ *
+ * @example```typescript
+ * const app = express();
+ * export const handler = ServerlessAdapter.new(app)
+ *   .setFramework(new ExpressFramework())
+ *   .setHandler(new DefaultHandler())
+ *   .setResolver(new PromiseResolver())
+ *   .setRespondWithErrors(true)
+ *   .addAdapter(new AlbAdapter())
+ *   .addAdapter(new SQSAdapter())
+ *   .addAdapter(new SNSAdapter())
+ *   .build();
+ * ```
+ */
+export declare class ServerlessAdapter<TApp, TEvent, TContext, TCallback, TResponse, TReturn> {
+    /**
+     * Default constructor
+     */
+    private constructor();
+    /**
+     * The instance of the app (express, hapi, koa, etc...)
+     */
+    protected app: TApp;
+    /**
+     * Settings for whether the response should be treated as binary or not
+     *
+     * @default `contentEncodings` and `contentTypes` are set with {@link DEFAULT_BINARY_ENCODINGS} and {@link DEFAULT_BINARY_ENCODINGS}, respectively.
+     */
+    protected binarySettings: BinarySettings;
+    /**
+     * Indicates whether the error stack should be included in the response or not
+     *
+     * @note These errors will only be included when an error occurs while forwarding the event to the framework
+     * @default True when NODE_ENV is equal to `development`
+     */
+    protected respondWithErrors: boolean;
+    /**
+     * The instance of the logger service
+     */
+    protected log: ILogger;
+    /**
+     * The list of adapters used to handle an event's request and response
+     */
+    protected adapters: AdapterContract<TEvent, TContext, TResponse>[];
+    /**
+     * The framework that will process requests
+     */
+    protected framework?: FrameworkContract<TApp>;
+    /**
+     * The resolver that aims to resolve the response to serverless and stop its execution when the request ends
+     */
+    protected resolver?: ResolverContract<TEvent, TContext, TCallback, TResponse, TReturn>;
+    /**
+     * The handler that will get the event, context and callback and pass it to the adapter and framework
+     */
+    protected handler?: HandlerContract<TApp, TEvent, TContext, TCallback, TResponse, TReturn>;
+    /**
+     * Creates a new instance of the builder with app (express, hapi, koa, etc...)
+     *
+     * @param app The instance of the app
+     */
+    static new<TApp, TEvent, TContext = any, TCallback = any, TResponse = any, TReturn = any>(app: TApp): ServerlessAdapter<TApp, TEvent, TContext, TCallback, TResponse, TReturn>;
+    /**
+     * Defines the handler that will get the event, context and callback and pass it to the adapter and framework
+     *
+     * @param handler The implementation of the handler contract
+     */
+    setHandler(handler: HandlerContract<TApp, TEvent, TContext, TCallback, TResponse, TReturn>): Omit<this, 'setHandler'>;
+    /**
+     * Defines the resolver that aims to resolve the response to serverless and stop its execution when the request ends
+     *
+     * @param resolver The implementation of the resolver contract
+     */
+    setResolver(resolver: ResolverContract<TEvent, TContext, TCallback, TResponse, TReturn>): Omit<this, 'setResolver'>;
+    /**
+     * Defines the framework that will process requests
+     *
+     * @param framework The implementation of the framework contract
+     */
+    setFramework(framework: FrameworkContract<TApp>): Omit<this, 'setFramework'>;
+    /**
+     * Defines the logger service used during the execution of the handler
+     *
+     * @param logger The implementation of the logger
+     */
+    setLogger(logger: ILogger): Omit<this, 'setLogger'>;
+    /**
+     * Defines the binary settings for whether the response should be treated as binary or not
+     *
+     * @param binarySettings The binary settings
+     */
+    setBinarySettings(binarySettings: BinarySettings): Omit<this, 'setBinarySettings'>;
+    /**
+     * Defines the responseWithErrors, a property that indicates whether the error stack should be included in the response or not
+     *
+     * @param respondWithErrors Should include or not the errors in response
+     */
+    setRespondWithErrors(respondWithErrors: boolean): Omit<this, 'setRespondWithErrors'>;
+    /**
+     * Add an adapter to the adapters list to handle the event coming from any serverless event source
+     *
+     * @param adapter The implementation of the adapter contract
+     */
+    addAdapter(adapter: AdapterContract<TEvent, TContext, TResponse>): Pick<this, 'addAdapter' | 'build'>;
+    /**
+     * The builder method that returns the handler function to be exported for serverless consumption
+     */
+    build(): ServerlessHandler<TReturn>;
+}

package/lib/serverless-adapter.js

@@ -0,0 +1,158 @@
+"use strict";
+//#region Imports
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServerlessAdapter = void 0;
+const core_1 = require("./core");
+//#endregion
+/**
+ * The class used to build the serverless handler.
+ *
+ * @example```typescript
+ * const app = express();
+ * export const handler = ServerlessAdapter.new(app)
+ *   .setFramework(new ExpressFramework())
+ *   .setHandler(new DefaultHandler())
+ *   .setResolver(new PromiseResolver())
+ *   .setRespondWithErrors(true)
+ *   .addAdapter(new AlbAdapter())
+ *   .addAdapter(new SQSAdapter())
+ *   .addAdapter(new SNSAdapter())
+ *   .build();
+ * ```
+ */
+class ServerlessAdapter {
+    //#region Constructor
+    /**
+     * Default constructor
+     */
+    constructor(app) {
+        //#endregion
+        //#region Protected Properties
+        /**
+         * Settings for whether the response should be treated as binary or not
+         *
+         * @default `contentEncodings` and `contentTypes` are set with {@link DEFAULT_BINARY_ENCODINGS} and {@link DEFAULT_BINARY_ENCODINGS}, respectively.
+         */
+        this.binarySettings = {
+            contentEncodings: core_1.DEFAULT_BINARY_ENCODINGS,
+            contentTypes: core_1.DEFAULT_BINARY_ENCODINGS,
+        };
+        /**
+         * Indicates whether the error stack should be included in the response or not
+         *
+         * @note These errors will only be included when an error occurs while forwarding the event to the framework
+         * @default True when NODE_ENV is equal to `development`
+         */
+        this.respondWithErrors = process.env.NODE_ENV === 'development';
+        /**
+         * The instance of the logger service
+         */
+        this.log = (0, core_1.createDefaultLogger)();
+        /**
+         * The list of adapters used to handle an event's request and response
+         */
+        this.adapters = [];
+        this.app = app;
+    }
+    //#endregion
+    //#region Static Methods
+    /**
+     * Creates a new instance of the builder with app (express, hapi, koa, etc...)
+     *
+     * @param app The instance of the app
+     */
+    static new(app) {
+        return new ServerlessAdapter(app);
+    }
+    //#endregion
+    //#region Builder Methods
+    /**
+     * Defines the handler that will get the event, context and callback and pass it to the adapter and framework
+     *
+     * @param handler The implementation of the handler contract
+     */
+    setHandler(handler) {
+        if (this.handler)
+            throw new Error('SERVERLESS_ADAPTER: The handler should not set twice.');
+        this.handler = handler;
+        return this;
+    }
+    /**
+     * Defines the resolver that aims to resolve the response to serverless and stop its execution when the request ends
+     *
+     * @param resolver The implementation of the resolver contract
+     */
+    setResolver(resolver) {
+        if (this.resolver)
+            throw new Error('SERVERLESS_ADAPTER: The resolver should not set twice.');
+        this.resolver = resolver;
+        return this;
+    }
+    /**
+     * Defines the framework that will process requests
+     *
+     * @param framework The implementation of the framework contract
+     */
+    setFramework(framework) {
+        if (this.framework) {
+            throw new Error('SERVERLESS_ADAPTER: The framework should not set twice.');
+        }
+        this.framework = framework;
+        return this;
+    }
+    /**
+     * Defines the logger service used during the execution of the handler
+     *
+     * @param logger The implementation of the logger
+     */
+    setLogger(logger) {
+        this.log = logger;
+        return this;
+    }
+    /**
+     * Defines the binary settings for whether the response should be treated as binary or not
+     *
+     * @param binarySettings The binary settings
+     */
+    setBinarySettings(binarySettings) {
+        this.binarySettings = binarySettings;
+        return this;
+    }
+    /**
+     * Defines the responseWithErrors, a property that indicates whether the error stack should be included in the response or not
+     *
+     * @param respondWithErrors Should include or not the errors in response
+     */
+    setRespondWithErrors(respondWithErrors) {
+        this.respondWithErrors = respondWithErrors;
+        return this;
+    }
+    /**
+     * Add an adapter to the adapters list to handle the event coming from any serverless event source
+     *
+     * @param adapter The implementation of the adapter contract
+     */
+    addAdapter(adapter) {
+        this.adapters.push(adapter);
+        return this;
+    }
+    /**
+     * The builder method that returns the handler function to be exported for serverless consumption
+     */
+    build() {
+        if (!this.resolver) {
+            throw new Error('SERVERLESS_ADAPTER: Is required to set a resolver before build.');
+        }
+        if (!this.framework) {
+            throw new Error('SERVERLESS_ADAPTER: Is required to set a framework before build.');
+        }
+        if (!this.handler) {
+            throw new Error('SERVERLESS_ADAPTER: Is required to set a handler before build.');
+        }
+        if (this.adapters.length === 0) {
+            throw new Error('SERVERLESS_ADAPTER: Is required to set at least one adapter.');
+        }
+        return this.handler.getHandler(this.app, this.framework, this.adapters, this.resolver, this.binarySettings, this.respondWithErrors, this.log);
+    }
+}
+exports.ServerlessAdapter = ServerlessAdapter;

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@h4ad/serverless-adapter",
+  "version": "1.0.1",
+  "description": "This library enables you to utilize any Cloud or Event Source to respond to web and API requests using your existing Node.js application framework.",
+  "main": "./lib/index.js",
+  "files": [
+    "lib/**/*"
+  ],
+  "scripts": {
+    "install:peers": "npx npm-install-peers",
+    "prepare": "husky install",
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf ./lib/",
+    "cm": "cz",
+    "coverage": "codecov",
+    "lint": "eslint ./src/ ./test/  --fix",
+    "semantic-release": "semantic-release",
+    "test:watch": "jest --watch",
+    "test": "jest --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/H4ad/serverless-adapter.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Vinícius Lourenço",
+    "email": "H4ad@users.noreply.github.com",
+    "url": "https://github.com/H4ad"
+  },
+  "engines": {
+    "node": ">=12.0"
+  },
+  "keywords": [
+    "aws",
+    "serverless",
+    "api gateway",
+    "sqs",
+    "sns",
+    "lambda-edge",
+    "alb",
+    "lambda",
+    "express",
+    "koa",
+    "hapi",
+    "fastify",
+    "node.js",
+    "http"
+  ],
+  "bugs": {
+    "url": "https://github.com/H4ad/serverless-adapter/issues"
+  },
+  "homepage": "https://github.com/H4ad/serverless-adapter#readme",
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.92",
+    "@types/body-parser": "^1.19.2",
+    "@types/jest": "^27.4.0",
+    "@types/node": "12.20.43",
+    "@typescript-eslint/eslint-plugin": "^5.12.1",
+    "@typescript-eslint/parser": "^5.12.1",
+    "body-parser": "^1.19.1",
+    "codecov": "^3.8.1",
+    "commitizen": "^4.2.4",
+    "cz-conventional-changelog": "^3.3.0",
+    "ejs": "^3.1.6",
+    "eslint": "^8.9.0",
+    "eslint-config-prettier": "^8.4.0",
+    "eslint-plugin-import": "^2.25.4",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "husky": "^6.0.0",
+    "jest": "^27.5.1",
+    "lint-staged": "^10.5.4",
+    "prettier": "^2.5.1",
+    "semantic-release": "^19.0.2",
+    "stream-mock": "^2.0.5",
+    "ts-jest": "^27.1.3",
+    "ts-node": "^10.4.0",
+    "typescript": "^4.5.5"
+  },
+  "peerDependencies": {
+    "@hapi/hapi": ">= 20.0.0",
+    "@types/express": ">= 4.15.4",
+    "@types/hapi": ">= 18.0.7",
+    "@types/koa": ">= 2.11.2",
+    "express": ">= 4.15.4",
+    "fastify": ">= 3.0.0",
+    "koa": ">= 2.5.1"
+  },
+  "peerDependenciesMeta": {
+    "@hapi/hapi": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "koa": {
+      "optional": true
+    },
+    "@types/express": {
+      "optional": true
+    },
+    "@types/hapi": {
+      "optional": true
+    },
+    "@types/koa": {
+      "optional": true
+    }
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
+  },
+  "lint-staged": {
+    "*.ts": "eslint --cache --cache-location .eslintcache --fix"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}