StackSpot DynamoDB Table construct library

A CDK construct for Typescript that can be used to create DynamoDB Table, give permissions for lambdas functions and generate commons commands.

The class _StackSpotDynamoDBTable_ in the construct extends the original CDK DynamoDB Table, we're extending it to facilitate the integration between StackSpot OpenAPI contract first API Gateway + Lambda construct library.

Prerequisites

- NodeJS 14.x -
- AWS account properly configured -
- AWS CDK CLI -

Optional (recommended) development tools

- Visual Studio Code (IDE) -
- Prettier VSCode extension (Code formatter) -
- Jest Runner VSCode extension (Runs jest tests from IDE) -

How to build library package

- To build the library package clone the repository and run npm scripts

``
git clone git@github.com:Stack-Spot/crystal-cdk-dynamodb.git
cd crystal-cdk-dynamodb
npm install
npm run build
npm run package
`

- The library will be built and package dynamodb@.jsii.tgz will be generated in dist/js folder

Quick start

The example bellow will create a simple CDK App using TypeScript and will create a DynamoDB Table.

$3

`
mkdir hello-world-app
cd hello-world-app
cdk init --language=typescript
`

$3

`
npm install @aws-cdk/aws-dynamodb @stackspot/cdk-component-dynamodb-typescript
`

$3

Open the file lib/hello-world-app-stack.ts that was generated by the CDK CLI like bellow:

`typescript
import * as cdk from '@aws-cdk/core';
import { StackSpotDynamoDBTable } from '@stackspot/cdk-component-dynamodb-typescript';
import { AttributeType } from '@aws-cdk/aws-dynamodb';

export class HelloWorldAppStack extends cdk.Stack {
constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);

new StackSpotDynamoDBTable(this, 'HelloWorldTable', {
tableConfiguration: {
partitionKey: { name: 'pk', type: AttributeType.STRING },
},
});
}
}
`

$3

`
cdk bootstrap --profile
`

If you have permissions problems related to S3 public access block configuration permissions on bootstrap you could add the option --public-access-block-configuration false to the bootstrap command as shown below:

`
cdk bootstrap --profile --public-access-block-configuration false
`

$3

To create any GSI, add gsis property array:

`typescript
import * as cdk from '@aws-cdk/core';
import { StackSpotDynamoDBTable } from '@stackspot/cdk-component-dynamodb-typescript';
import { AttributeType } from '@aws-cdk/aws-dynamodb';

export class HelloWorldAppStack extends cdk.Stack {
constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
super(scope, id, props);

new StackSpotDynamoDBTable(this, 'HelloWorldTable', {
tableConfiguration: {
partitionKey: { name: 'pk', type: AttributeType.STRING },
sortKey: { name: 'sk', type: AttributeType.STRING },
},
gsis: [
{
indexName: 'my-gsi-index',
partitionKey: { name: 'sk', type: AttributeType.STRING },
},
],
});
}
}
`

$3

Run npm run build and cdk deploy.

Check in AWS Console the DynamoDB table created.

Integrating with StackSpot OpenAPI Typescript Lambda construct

The best part of this construct is to facilitate the integration between the table and lambdas created by StackSpot OpenAPI contract first API Gateway + Lambda construct library.

Check the StackSpot OpenAPI contract first API Gateway + Lambda construct library docs to learn more.

Then you can integrate the constructs using lambdasConfiguration properties:

`typescript
const lambdas = new StackSpotOpenApiServices(this, 'HelloWorldApi', {
specPath: 'spec/hello-world.yaml',
});

new StackSpotDynamoDBTable(this, 'HelloWorldTable', {
tableConfiguration: {
partitionKey: { name: 'pk', type: AttributeType.STRING },
},
lambdasConfiguration: {
lambdasById: lambdas.backendLambdas,
tableNameEnvironmentVariable: 'MY_DYNAMO_TABLE_NAME',
},
});
`

Now all the lambdas will have permissions to read and write to the DynamoDB table.

$3

To set readOnly permission to your lambda use readOnly property with the operation-id name defined in your OpenAPI Spec:

`typescript
const lambdas = new StackSpotOpenApiServices(this, 'HelloWorldApi', {
specPath: 'spec/hello-world.yaml',
});

new StackSpotDynamoDBTable(this, 'HelloWorldTable', {
tableConfiguration: {
partitionKey: { name: 'pk', type: AttributeType.STRING },
},
lambdasConfiguration: {
lambdasById: lambdas.backendLambdas,
tableNameEnvironmentVariable: 'MY_DYNAMO_TABLE_NAME',
readOnly: ['list-hello', 'get-hello'],
},
});
`

Generate DynamoDB commons commands

Some commons commands (insert, queries, updates and deletes) are commons and required for all sort off applications, so this construct is generating some helper functions to help you with this task.

To let the construct generate the code, set the StackSpotDynamoDBTable like bellow:

`typescript
new StackSpotDynamoDBTable(this, 'HelloWorldTable', {
// other settings...
generateRepository: true,
});
`

If you'd like to configure some options, add the repositoryGenerationConfiguration object, like:

`typescript
new StackSpotDynamoDBTable(this, 'HelloWorldTable', {
// other settings...
generateRepository: true,
repositoryGenerationConfiguration: {
tracing: false,
sourceDir: 'src',
},
});
`

- tracing - enable x-ray tracing - _default: true_
- sourceDir - change the default source foldes: _default: src_

Useful commands

- npm run build compile typescript to jsii
- npm run watch watch for changes and compile
- npm run test perform the jest unit tests
- npm run package package library using jsii
- npm run coverage` run tests with coverage reports

References

$3

- - CDK Developer guide
- - CDK Amazon API Gateway Construct Library
- - jsii library author guide
- - CDK advanced workshop
- - CDK Videos
- - CDK DynamoDB Construct Library