{"id":16077717,"url":"https://github.com/BeerMoneyDev/nest-aws-sdk","last_synced_at":"2025-10-22T20:30:44.479Z","repository":{"id":45875312,"uuid":"282094021","full_name":"BeerMoneyDev/nest-aws-sdk","owner":"BeerMoneyDev","description":"A thin wrapping layer around the aws-sdk package for clean NestJS dependency injection.","archived":false,"fork":false,"pushed_at":"2024-10-17T14:06:51.000Z","size":1165,"stargazers_count":93,"open_issues_count":4,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T00:12:47.194Z","etag":null,"topics":["aws","aws-sdk","nest","nestjs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BeerMoneyDev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-24T01:33:03.000Z","updated_at":"2024-10-17T14:06:53.000Z","dependencies_parsed_at":"2024-06-18T16:43:05.880Z","dependency_job_id":"fc1395a0-7ec6-4307-a7e9-6595ad34e50f","html_url":"https://github.com/BeerMoneyDev/nest-aws-sdk","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-aws-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-aws-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-aws-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BeerMoneyDev%2Fnest-aws-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BeerMoneyDev","download_url":"https://codeload.github.com/BeerMoneyDev/nest-aws-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237739846,"owners_count":19358624,"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","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","aws-sdk","nest","nestjs"],"created_at":"2024-10-09T10:02:20.849Z","updated_at":"2025-10-22T20:30:44.085Z","avatar_url":"https://github.com/BeerMoneyDev.png","language":"TypeScript","funding_links":[],"categories":["aws"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003enest-aws-sdk\u003c/h1\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://beermoneydev-assets.s3.amazonaws.com/nest-aws-sdk-logo.png\" /\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eA thin wrapping layer around the \u003ca href=\"https://github.com/aws/aws-sdk-js\" target=\"_blank\"\u003eaws-sdk\u003c/a\u003e (AWS SDK v2) package for clean \u003ca href=\"https://github.com/nestjs\"\u003eNestJS\u003c/a\u003e dependency injection.\u003c/strong\u003e\n\u003c/div\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"https://www.npmjs.com/package/nest-aws-sdk\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/nest-aws-sdk.svg\" alt=\"NPM Version\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/nest-aws-sdk\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/nest-aws-sdk.svg\" alt=\"Package License\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://www.npmjs.com/package/nest-aws-sdk\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/nest-aws-sdk.svg\" alt=\"NPM Downloads\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# Features\n\n- Decorator for injecting AWS services.\n- An AWS service factory for on-the-fly AWS client creation.\n- A simple dependency injection model with AwsSdkModule.forRootAsync() and AwsSdkModule.forFeature().\n- Helper test tools for creating mocked AWS clients.\n\n# How To Use\n\n## Install\n\n```bash\nnpm install --save nest-aws-sdk aws-sdk\n```\n\n## Basic Usage - Root-level feature registration\n\nBelow is an example of injecting the AwsSdkModule at the global root level. This also demonstrates some of the testing tools provided to make mocking and spying on AWS clients easier.\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { AwsSdkModule } from 'nest-aws-sdk';\nimport { SharedIniFileCredentials, S3 } from 'aws-sdk';\nimport { ServiceConfigurationOptions } from 'aws-sdk/lib/service';\nimport { S3ManagerModule } from './s3-manager/s3-manager.module';\n\n@Module({\n  imports: [\n    S3ManagerModule,\n    AwsSdkModule.forRoot({\n      defaultServiceOptions: {\n        region: 'us-east-1',\n        credentials: new SharedIniFileCredentials({\n          profile: 'my-profile',\n        }),\n      },\n      services: [S3],\n    }),\n  ],\n  providers: [],\n  exports: [],\n})\nexport class AppModule {}\n```\n\n```ts\n// s3-manager.module.ts\nimport { Module } from '@nestjs/common';\nimport { S3ManagerService } from './s3-manager.service';\n\n@Module({\n  imports: [],\n  providers: [S3ManagerService],\n  exports: [S3ManagerService],\n})\nclass S3ManagerModule {}\n```\n\n```ts\n// s3-manager.service.ts\nimport { Injectable } from '@nestjs/common';\nimport { InjectAwsService } from 'nest-aws-sdk';\nimport { S3 } from 'aws-sdk';\n\n@Injectable()\nexport class S3ManagerService {\n  constructor(@InjectAwsService(S3) private readonly s3: S3) {}\n\n  async listBucketContents(bucket: string) {\n    const response = await this.s3.listObjectsV2({ Bucket: bucket }).promise();\n    return response.Contents.map(c =\u003e c.Key);\n  }\n}\n```\n\n```ts\n// s3-manager.service.spec.ts\nimport { Test, TestingModule } from '@nestjs/testing';\nimport { S3 } from 'aws-sdk';\nimport {\n  createAwsServiceMock,\n  createAwsServicePromisableSpy,\n  getAwsServiceMock,\n} from 'nest-aws-sdk/dist/testing';\nimport { S3ManagerService } from './s3-manager.service';\n\ndescribe('S3ManagerService', () =\u003e {\n  describe('listBucketContents()', () =\u003e {\n    it('should call the list method and return the Content keys', async () =\u003e {\n      const module: TestingModule = await Test.createTestingModule({\n        providers: [\n          S3ManagerService,\n          createAwsServiceMock(S3, {\n            useValue: {\n              listObjectsV2: () =\u003e null,\n            },\n          }),\n        ],\n      }).compile();\n\n      const service = module.get(S3ManagerService);\n\n      const listSpy = createAwsServicePromisableSpy(\n        getAwsServiceMock(module, S3),\n        'listObjectsV2',\n        'resolve',\n        {\n          Contents: [{ Key: 'myKey' }],\n        },\n      );\n\n      const result = await service.listBucketContents('myBucket');\n\n      expect(result.length).toBe(1);\n      expect(result[0]).toBe('myKey');\n      expect(listSpy).toHaveBeenCalledTimes(1);\n      expect(listSpy).toHaveBeenCalledWith({ Bucket: 'myBucket' });\n    });\n  });\n});\n```\n\n## Basic Usage - Module-level feature registration\n\nBelow is an example of injecting the AwsSdkModule global providers at the root-level and the client feature registration at the feature-submodule.\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { AwsSdkModule } from 'nest-aws-sdk';\nimport { SharedIniFileCredentials } from 'aws-sdk';\nimport { ServiceConfigurationOptions } from 'aws-sdk/lib/service';\nimport { S3ManagerModule } from './s3-manager/s3-manager.module';\n\n@Module({\n  imports: [\n    S3ManagerModule,\n    AwsSdkModule.forRootAsync({\n      defaultServiceOptions: {\n        useValue: {\n          region: 'us-east-1',\n          credentials: new SharedIniFileCredentials({\n            profile: 'my-profile',\n          }),\n        },\n      },\n    }),\n  ],\n  providers: [],\n  exports: [],\n})\nexport class AppModule {}\n```\n\n```ts\n// s3-manager.module.ts\nimport { Module } from '@nestjs/common';\nimport { AwsSdkModule } from 'nest-aws-sdk';\nimport { S3 } from 'aws-sdk';\nimport { S3ManagerService } from './s3-manager.service';\n\n@Module({\n  imports: [AwsSdkModule.forFeatures([S3])],\n  providers: [S3ManagerService],\n  exports: [S3ManagerService],\n})\nclass S3ManagerModule {}\n```\n\n## AwsSdkModule.forRoot()\n\n`AwsSdkModule.forRoot()` is the simplest form of registration and uses statically assigned `options` values.\n\n### options\n\n#### defaultServiceOptions?: Partial\u003cServiceConfigurationOptions\u003e | (() =\u003e Partial\u003cServiceConfigurationOptions\u003e);\n\n`defaultServiceOptions` is an optional object or object-returning method to get the aws-sdk `ServiceConfigurationOptions` object. This includes the `region`, `credentials`, and other client-level configuration.\n\n#### services?: Array\u003cAwsServiceType\u003cAwsService\u003e | AwsServiceWithServiceOptions\u003e,\n\n`services` can optionally be registered at the root level by passing an array of aws-sdk types, i.e. `S3`, or a `AwsServiceWithServiceOptions` object. These are interchangable and can be used as such:\n\n```ts\nimport { AwsSdkModule } from 'nest-aws-sdk';\nimport { CloudFront, S3, SharedIniFileCredentials } from 'aws-sdk';\n\n@Module({\n  imports: [\n    AwsSdkModule.forRoot({\n      services: [\n        S3,\n        {\n          service: CloudFront,\n          serviceOptions: {\n            credentials: new SharedIniFileCredentials({\n              profile: 'aws-nest-sdk',\n            }),\n          },\n        },\n      ],\n    }),\n  ],\n})\nclass AppRootModule {}\n```\n\n**Note: the supplied values in serviceOptions will override the values supplied in the defaultServiceOptions object.**\n\n## forRootAsync\n\n`AwsSdkModule.forRootAsync()` is an injectable form of the `AwsSdkModule.forRoot()` import and currently supports two types of instantiation: 'useFactory' and 'useValue'. Support for ClassProvider and ExistingProvider coming soon.\n\n### No parameters\n\n`AwsSdkModule.forRootAsync()` can be called with no provided parameters. This will allow the AWS clients to be created without any provided credential context, which is not uncommon when running in an AWS environment.\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { AwsSdkModule } from 'nest-aws-sdk';\nimport { S3ManagerModule } from './s3-manager/s3-manager.module';\n\n@Module({\n  imports: [S3ManagerModule, AwsSdkModule.forRootAsync()],\n  providers: [],\n  exports: [],\n})\nexport class AppModule {}\n```\n\n### useValue\n\nuseValue is the simplest way to modify the service options of the created clients.\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { AwsSdkModule } from 'nest-aws-sdk';\nimport { SharedIniFileCredentials } from 'aws-sdk';\nimport { ServiceConfigurationOptions } from 'aws-sdk/lib/service';\nimport { S3ManagerModule } from './s3-manager/s3-manager.module';\n\n@Module({\n  imports: [\n    S3ManagerModule,\n    AwsSdkModule.forRootAsync({\n      defaultServiceOptions: {\n        useValue: {\n          region: 'us-east-1',\n          credentials: new SharedIniFileCredentials({\n            profile: 'my-profile',\n          }),\n        },\n      },\n    }),\n  ],\n  providers: [],\n  exports: [],\n})\nexport class AppModule {}\n```\n\n### useFactory\n\nuseFactory allows for dynamic modification of the service options. This includes support for `imports` and `inject`.\n\n```ts\n// app.module.ts\nimport { Module } from '@nestjs/common';\nimport { AwsSdkModule } from 'nest-aws-sdk';\nimport { ConfigService, ConfigModule } from './config';\n\n@Module({\n  imports: [\n    AwsSdkModule.forRootAsync({\n      defaultServiceOptions: {\n        useFactory: (cs: ConfigService) =\u003e {\n          return {\n            region: 'us-east-1',\n            credentials: cs.getCredentials(),\n          };\n        },\n        imports: [ConfigModule],\n        inject: [ConfigService],\n      },\n    }),\n  ],\n  providers: [],\n  exports: [],\n})\n```\n\n## AwsSdkModule.forFeatures()\n\n`AwsSdkModule.forFeatures()` creates the providers for the AWS clients you wish to use at a module-specific level.\n\n**Note: forFeatures cannot be used in combination with root-level service registrations.**\n\n### Basic usage\n\nTo provide clients to the module context, pass the client constructor symbol to the `AwsSdkModule.forFeatures()` method. Note, it is best to import the client directly from `aws-sdk` instead of from deeper paths - the deeper paths may produce unexpected behaviors.\n\n```ts\nimport { Module } from '@nestjs/common';\nimport { S3 } from 'aws-sdk';\nimport { AwsSdkModule } from 'nest-aws-sdk';\n\n@Module({\n  imports: [AwsSdkModule.forFeatures([S3])],\n  providers: [],\n  exports: [],\n})\nclass AppSubModule {}\n```\n\n## AwsServiceFactory\n\nThe `AwsServiceFactory` class is exposed to the root- and feature-level. This allows for dynamic creation of AWS clients without feature registration. In addition, the default options are injectable via the `@InjectAwsDefaultOptions()` decorator.\n\n```ts\nimport { Injectable } from '@nestjs/common';\nimport { InjectAwsDefaultOptions } from '../src';\nimport { S3, SharedIniFileCredentials } from 'aws-sdk';\nimport { ServiceConfigurationOptions } from 'aws-sdk/lib/service';\n\n@Injectable()\nexport class AppService {\n  constructor(\n    @InjectAwsDefaultOptions() readonly options: ServiceConfigurationOptions,\n    readonly factory: AwsServiceFactory,\n  ) {}\n}\n```\n\n## Testing\n\nFor testing AWS clients, we recommend fully replacing the AWS clients as they have side-effects inside of the constructor. To do so, methods are made available to make mocking these clients very simple.\n\n### createAwsServiceMock\n\nThis method allows for override an AWS client instantiation. To mock a client, call the `createAwsServiceMock` method with the client constructor and pass a provider object that will be used in its stead.\n\n```ts\nconst module: TestingModule = await Test.createTestingModule({\n  providers: [\n    S3ManagerService,\n    createAwsServiceMock(S3, {\n      useValue: {\n        listObjectsV2: () =\u003e null,\n      },\n    }),\n  ],\n}).compile();\n```\n\n### getAwsServiceMock\n\nTo retrieve a mock from the test bed via the correct symbol, `getAwsServiceMock` is exported.\n\n```ts\nconst s3 = getAwsServiceMock(module, S3);\n```\n\n### createAwsServicePromisableSpy\n\nIt is common to want to use the `.promise()` method returned by most AWS client methods. To make spying on these simpler, the `createAwsServicePromisableSpy` creates a spy and returns a promised value.\n\n```ts\nit('should call the list method and return the Content keys', async () =\u003e {\n  const listSpy: jest.SpyInstance = createAwsServicePromisableSpy(\n    s3, // the mocked object to spy on\n    'listObjectsV2', // the method to spy on\n    'resolve', // 'resolve' or 'reject'\n    { Contents: [{ Key: 'myKey' }] }, // the value to resolve or reject\n  );\n\n  const result = await service.listBucketContents('myBucket');\n\n  expect(result.length).toBe(1);\n  expect(result[0]).toBe('myKey');\n  expect(listSpy).toHaveBeenCalledTimes(1);\n  expect(listSpy).toHaveBeenCalledWith({ Bucket: 'myBucket' });\n});\n```\n\n# Stay In Touch\n\n- Author - [Kerry Ritter](https://twitter.com/kerryritter) and BeerMoneyDev\n\n## License\n\nnest-aws-sdk is MIT licensed.\n\n## Contributing\n\nNest-AWS-SDK is released through [semantic-release](https://github.com/semantic-release/semantic-release). Effectively this means that versioning is based off commit messages. Please review [angular-changelog-convention](https://github.com/conventional-changelog-archived-repos/conventional-changelog-angular/blob/master/convention.md) and commit under that format. Otherwise semantic-release won't pick up commits for versioning this library.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBeerMoneyDev%2Fnest-aws-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FBeerMoneyDev%2Fnest-aws-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FBeerMoneyDev%2Fnest-aws-sdk/lists"}