{"id":28296885,"url":"https://github.com/andrea-lascola/aws-nodejs-kit","last_synced_at":"2025-08-02T08:08:00.054Z","repository":{"id":42263747,"uuid":"271367578","full_name":"andrea-lascola/aws-nodejs-kit","owner":"andrea-lascola","description":"A collection of helpers to manage common tasks in aws lambda: ex. input validation/apigw responses/error management...","archived":false,"fork":false,"pushed_at":"2023-01-12T01:43:36.000Z","size":1214,"stargazers_count":5,"open_issues_count":8,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-29T17:04:15.132Z","etag":null,"topics":["aws","lambda","nodejs","serverless","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/andrea-lascola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-10T19:31:40.000Z","updated_at":"2025-03-07T16:17:07.000Z","dependencies_parsed_at":"2023-02-09T09:17:53.518Z","dependency_job_id":null,"html_url":"https://github.com/andrea-lascola/aws-nodejs-kit","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/andrea-lascola/aws-nodejs-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrea-lascola%2Faws-nodejs-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrea-lascola%2Faws-nodejs-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrea-lascola%2Faws-nodejs-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrea-lascola%2Faws-nodejs-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andrea-lascola","download_url":"https://codeload.github.com/andrea-lascola/aws-nodejs-kit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andrea-lascola%2Faws-nodejs-kit/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267890313,"owners_count":24161397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","lambda","nodejs","serverless","typescript"],"created_at":"2025-05-22T22:13:40.260Z","updated_at":"2025-08-02T08:08:00.046Z","avatar_url":"https://github.com/andrea-lascola.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Release](https://github.com/andrea-lascola/aws-nodejs-kit/workflows/Release/badge.svg)\n\n# Aws Nodejs Kit\n\nThis is a collection of generic typescript utilities to use in an aws lambda powered environment\n\nTable of Contents\n=================\n  * [Installation](#installation)\n  * [Usage / Reference](#usage--reference)\n     * [NodeJS / Typescript utilities](#nodejs--typescript-utilities)\n        * [Monads](#monads)\n        * [Logger](#logger)\n        * [Logging Decorators](#logging-decorators)\n        * [Dates](#dates)\n        * [Exceptions](#exceptions)\n     * [AWS Helpers](#aws-helpers)\n        * [Lambda Core](#lambda-core)\n        * [Lambda Middlewares](#lambda-middlewares)\n        * [DynamoDb](#dynamodb)\n        * [Api Gateway](#api-gateway)\n  * [Contributing](#contributing)\n\n## Installation\n\nnpm page: https://www.npmjs.com/package/aws-nodejs-kit\n\n    npm i aws-nodejs-kit \n\n## Usage / Reference\n\nPlease refer to the _/examples_ folder \n\n### NodeJS / Typescript utilities\n\n#### Monads\n```typescript\nimport {Optional} from \"aws-nodejs-kit\";\n\nconst value: number | undefined = 10;\n\n// Perform a list of computation without having to check explicitly for null/undefined value\nconst compute = Optional.fromValue(value)\n    .map((val: number) =\u003e val + 10)\n    .map((val: number) =\u003e val * 2)\n    // Get the internal value, you can actually apply a default if the value is undefined\n    .getOrElse(10);\n\nconsole.log(compute); // 40\n```\n\n#### Logger\n```typescript\nimport {Logger} from \"aws-nodejs-kit\";\n\n// Static Logger\nconst log = Logger.getInstance();\n\n// Standard logs\nlog.debug(\"debug\");\nlog.info(\"info\");\nlog.warn(\"warn\");\nlog.error(\"error\");\n\n\n// Log performance\nlog.time(\"log\");\nlog.timeEnd(\"log\");\n```\n\n#### Logging Decorators\n```typescript\nimport {CatchExceptionAndThrowIntegrationError} from \"aws-nodejs-kit\";\nimport {LogMetric, LogMetricSync} from \"aws-nodejs-kit\";\n\nclass Service {\n\n    // Log Metric for async functions\n    // This will result in the following log row:\n    // METRIC 1021.351594000007 milliseconds getFeedByName feeds\n    @LogMetric(\"getFeedByName\", \"feeds\")\n    public async getFeedByName() {\n\n    }\n\n    // Log Metric for sync functions\n    // This will result in the following log row:\n    // METRIC 1021.351594000007 milliseconds getFeedById feeds\n    @LogMetricSync(\"getFeedById\", \"feeds\")\n    public getFeedById() {\n\n    }\n\n    // Catch errors for async functions\n    // throw an IntegrationError, that, if used in conjuction with \"catchErrors\" Middleware generate a 429 http error\n    // Used to propagate an integration error\n    @CatchExceptionAndThrowIntegrationError()\n    public async getFeedFromExternal() {\n\n    }\n}\n```\n\n#### Dates\n```typescript\nimport {dates} from \"aws-nodejs-kit\";\n\ndates.datePlusTimeframe(new Date(), 1, dates.TimeUnit.hours);\n// 2020-06-15T20:38:14.953Z\n\ndates.dateFromISO(new Date().toISOString());\n// 2020-06-15T19:38:14.956Z\n\ndates.dateInHyphens(new Date());\n// 2020-06-15\n\ndates.dateInSeconds(new Date());\n// 1592249894\n\ndates.dateMinusTimeframe(new Date, 1, dates.TimeUnit.hours);\n// 2020-06-15T18:38:14.960Z\n\ndates.isDateGreaterThan(new Date(), 1, dates.TimeUnit.hours);\n// true\n\ndates.iSOFromTimestamp(new Date().getTime());\n// 2020-06-15T19:41:11.301Z\n\ndates.timestampFromISO(new Date().toISOString());\n// 1592250071303\n\ndates.timeframeToSeconds({amount: 1, timeUnit: dates.TimeUnit.hours});\n// 3600\n```\n\n#### Exceptions\n```typescript\nimport {\n    ValidationError,        // Maps to a 400 Status code\n    UseCaseError,           // Maps to a 422 Status code\n    IntegrationError,       // Maps to a 429 Status code\n    NotFoundError,          // Maps to a 400 Status code\n    UnAuthorizedError,      // Maps to a 401 Status code\n    NotImplementedError,    // Used for abstract classes\n} from \"aws-nodejs-kit\";\n```\n\n\n### AWS Helpers\n\n#### Lambda Core\n```typescript\nimport {catchErrors, Lambda} from \"aws-nodejs-kit\";\nimport {Logger} from \"aws-nodejs-kit\";\n/**\n * Classic handler with business logic\n * @param event\n */\nconst handler = async (event: any) =\u003e {\n    console.log(event);\n};\n\n// export a lambda Handler using handler\nexport const lambdaHandler = new Lambda(handler)\n    // Add any middleware you need, this one catch errors and respond with standard api gateway responses\n    .with(catchErrors(Logger.getInstance()))\n    // Applying Middlewares\n    .toFn();\n```\n\n#### Lambda Middlewares\n```typescript\n// --- Default Middlewares includes:\n\n// Log Lambda input event\n.with(logEvent(Logger.getInstance()))\n\n// Log Lambda response\n.with(logResponse(Logger.getInstance()))\n\n// Catch errors globally and return a apigw compatible response (map exceptions to status codes)\n.with(catchErrors(Logger.getInstance()))\n\n// Validate Lambda input event against a DTO (class decorated with \"class-validator\" decorators with static method \"fromApiGWEvent\")\n// uses validate function to check- you should pass the \"validator\" function from \"class-validator\"  \n.with(validateDTO(Logger.getInstance(),\n    (event) =\u003e MyDTO.fromApiGWEvent(event),\n    validate))\n\n// You can create your custom Middleware implementing the \"Middleware\" type and passing your object to the .with() function\n```\n\n#### DynamoDb\n```typescript\n// TODO complete doc\n```\n#### Api Gateway\n```typescript\n\nimport {ResponseBuilder} from \"aws-nodejs-kit\";\n\nlet handler;\n\n/**\n * Return Api Gateway compatible responses\n * @param event\n */\nhandler = async (event: any) =\u003e {\n    /**\n     * http status code -\u003e 200\n     * response(enveloped) -\u003e {\n     *     data : {}\n     * }\n     */\n    return new ResponseBuilder().build().resOk({data: {}});\n    /**\n     * http status code -\u003e 204\n     * response(enveloped) -\u003e {\n     *     data : {}\n     * }\n     * used mainly for POST/DELETE/PUT APIs\n     */\n    return new ResponseBuilder().build().resOkNoContent({data: {}});\n};\n\n\n/**\n * Return Bad Request responses:\n *\n * response(enveloped) -\u003e {\n *      error: {\n *          errorMessage: errorMessage || \"The request could not be understood by the server due to malformed syntax. The client should not repeat the request without modifications\",\n *          errorCode: errorCode || \"\",\n *          payload\n *      }\n * }\n * @param event\n */\nhandler = async (event: any) =\u003e {\n    /**\n     * http status code -\u003e 400\n     */\n    return new ResponseBuilder().build().resBadReq(\n        {}, // optional payload,\n        \"xxx\", // optional errorCode,\n        \"Invalid\" // optional errorMessage,\n    );\n    /**\n     * http status code -\u003e 404\n     * used for missing content\n     */\n    return new ResponseBuilder().build().resNotFound();\n    /**\n     * http status code -\u003e 429\n     * an error while communicating with a third party service happened\n     */\n    return new ResponseBuilder().build().resIntegrationError();\n    /**\n     * http status code -\u003e 422\n     * used for a business logic un-manageable error (better than a 500 aint'it?)\n     */\n    return new ResponseBuilder().build().resUseCaseError();\n    /**\n     * http status code -\u003e 403\n     * you are not allowed to see this content\n     */\n    return new ResponseBuilder().build().resForbidden();\n};\n\n```\n\n\n\n## Contributing\n\n    npm install\n    npm run build\n    npm run test\n    npm run test:coverage // tests with coverage report\n\n* PRs are welcome\n* The release process uses github actions and **semantic-release** for automatic tagging/versioning/publishing to npm\n* The commit messages MUST follow the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) convention \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrea-lascola%2Faws-nodejs-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandrea-lascola%2Faws-nodejs-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandrea-lascola%2Faws-nodejs-kit/lists"}