docs(examples): add example for AWS SAM

.gitignore

@@ -39,3 +39,6 @@ site
 
 # Generated API documentation (from TypeDoc)
 /api
+
+# SAM Example copies files
+/examples/sam/src/handlers/*.ts

examples/lambda-functions/get-all-items.ts

@@ -0,0 +1,87 @@
+import { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { DynamoDB } from 'aws-sdk';
+
+// Create the PowerTools clients
+const metrics = new Metrics();
+const logger = new Logger();
+const tracer = new Tracer();
+
+// Create DynamoDB DocumentClient and patch it for tracing
+const docClient = tracer.captureAWS(new DynamoDB.DocumentClient());
+
+// Get the DynamoDB table name from environment variables
+const tableName = process.env.SAMPLE_TABLE;
+
+/**
+ *
+ * Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
+ * @param {Object} event - API Gateway Lambda Proxy Input Format
+ *
+ * Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
+ * @returns {Object} object - API Gateway Lambda Proxy Output Format
+ *
+ */
+
+export const getAllItemsHandler = async (event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult> => {
+  if (event.httpMethod !== 'GET') {
+    throw new Error(`getAllItems only accepts GET method, you tried: ${event.httpMethod}`);
+  }
+  // Tracer: Get facade segment created by AWS Lambda
+  const segment = tracer.getSegment();
+
+  // Tracer: Create subsegment for the function & set it as active
+  const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+  tracer.setSegment(handlerSegment);
+
+  // Tracer: Annotate the subsegment with the cold start & serviceName
+  tracer.annotateColdStart();
+  tracer.addServiceNameAnnotation();
+
+  // Tracer: Add annotation for the awsRequestId
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+
+  // Metrics: Capture cold start metrics
+  metrics.captureColdStartMetric();
+
+  // All log statements are written to CloudWatch
+  logger.debug('received:', event);
+
+  // get all items from the table (only first 1MB data, you can use `LastEvaluatedKey` to get the rest of data)
+  // https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#scan-property
+  // https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html
+  const params = {
+    TableName: tableName!
+  };
+
+  let response;
+
+  try {
+    const data = await docClient.scan(params).promise();
+    const items = data.Items;
+    response = {
+      statusCode: 200,
+      body: JSON.stringify(items)
+    };
+  } catch (err) {
+    tracer.addErrorAsMetadata(err as Error);
+    logger.error('Error reading from table. ' + err);
+    response = {
+      statusCode: 500,
+      body: JSON.stringify({ 'error': 'Error reading from table.' })
+    };
+  }
+
+  // Tracer: Close subsegment (the AWS Lambda one is closed automatically)
+  handlerSegment.close(); // (## index.handler)
+
+  // Tracer: Set the facade segment as active again (the one created by AWS Lambda)
+  tracer.setSegment(segment);
+
+  // All log statements are written to CloudWatch
+  logger.info(`response from: ${event.path} statusCode: ${response.statusCode} body: ${response.body}`);
+
+  return response;
+};

examples/lambda-functions/get-by-id.ts

@@ -0,0 +1,90 @@
+import { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { DynamoDB } from 'aws-sdk';
+
+// Create the PowerTools clients
+const metrics = new Metrics();
+const logger = new Logger();
+const tracer = new Tracer();
+
+// Create DynamoDB DocumentClient and patch it for tracing
+const docClient = tracer.captureAWS(new DynamoDB.DocumentClient());
+
+// Get the DynamoDB table name from environment variables
+const tableName = process.env.SAMPLE_TABLE;
+
+/**
+ *
+ * Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
+ * @param {Object} event - API Gateway Lambda Proxy Input Format
+ *
+ * Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
+ * @returns {Object} object - API Gateway Lambda Proxy Output Format
+ *
+ */
+
+export const getByIdHandler = async (event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult> => {
+  if (event.httpMethod !== 'GET') {
+    throw new Error(`getById only accepts GET method, you tried: ${event.httpMethod}`);
+  }
+  // Tracer: Get facade segment created by AWS Lambda
+  const segment = tracer.getSegment();
+
+  // Tracer: Create subsegment for the function & set it as active
+  const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+  tracer.setSegment(handlerSegment);
+
+  // Tracer: Annotate the subsegment with the cold start & serviceName
+  tracer.annotateColdStart();
+  tracer.addServiceNameAnnotation();
+
+  // Tracer: Add annotation for the awsRequestId
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+
+  // Metrics: Capture cold start metrics
+  metrics.captureColdStartMetric();
+
+  // All log statements are written to CloudWatch
+  logger.debug('received:', event);
+
+  // Get id from pathParameters from APIGateway because of `/{id}` at template.yaml
+  const id = event.pathParameters!.id;
+
+  // Get the item from the table
+  // https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#get-property
+  const params = {
+    TableName: tableName!,
+    Key: { id: id },
+  };
+
+  let response;
+
+  try {
+    const data = await docClient.get(params).promise();
+    const item = data.Item;
+    response = {
+      statusCode: 200,
+      body: JSON.stringify(item)
+    };
+  } catch (err) {
+    tracer.addErrorAsMetadata(err as Error);
+    logger.error('Error reading from table. ' + err);
+    response = {
+      statusCode: 500,
+      body: JSON.stringify({ 'error': 'Error reading from table.' })
+    };
+  }
+
+  // Tracer: Close subsegment (the AWS Lambda one is closed automatically)
+  handlerSegment.close(); // (## index.handler)
+
+  // Tracer: Set the facade segment as active again (the one created by AWS Lambda)
+  tracer.setSegment(segment);
+
+  // All log statements are written to CloudWatch
+  logger.info(`response from: ${event.path} statusCode: ${response.statusCode} body: ${response.body}`);
+
+  return response;
+};

examples/lambda-functions/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "hello_world",
+  "version": "1.0.0",
+  "description": "AWS Lambda Powertools for TypeScript Sample",
+  "author": "SAM CLI",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-lambda-powertools/logger": "^0.7.0",
+    "@aws-lambda-powertools/metrics": "^0.7.0",
+    "@aws-lambda-powertools/tracer": "^0.7.0"
+  },
+  "scripts": {
+    "lint": "eslint '*.ts' --quiet --fix",
+    "compile": "tsc"
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.86",
+    "@types/node": "17.0.10",
+    "@typescript-eslint/parser": "^5.12.1",
+    "esbuild": "^0.14.23",
+    "eslint": "^8.4.0",
+    "ts-node": "^10.0.0",
+    "typescript": "^4.1.3"
+  }
+}

examples/lambda-functions/put-item.ts

@@ -0,0 +1,91 @@
+import { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { DynamoDB } from 'aws-sdk';
+
+// Create the PowerTools clients
+const metrics = new Metrics();
+const logger = new Logger();
+const tracer = new Tracer();
+
+// Create DynamoDB DocumentClient and patch it for tracing
+const docClient = tracer.captureAWS(new DynamoDB.DocumentClient());
+
+// Get the DynamoDB table name from environment variables
+const tableName = process.env.SAMPLE_TABLE;
+
+/**
+ *
+ * Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
+ * @param {Object} event - API Gateway Lambda Proxy Input Format
+ *
+ * Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
+ * @returns {Object} object - API Gateway Lambda Proxy Output Format
+ *
+ */
+
+export const putItemHandler = async (event: APIGatewayProxyEvent, context: Context): Promise<APIGatewayProxyResult> => {
+  if (event.httpMethod !== 'POST') {
+    throw new Error(`putItem only accepts POST method, you tried: ${event.httpMethod}`);
+  }
+  // Tracer: Get facade segment created by AWS Lambda
+  const segment = tracer.getSegment();
+
+  // Tracer: Create subsegment for the function & set it as active
+  const handlerSegment = segment.addNewSubsegment(`## ${process.env._HANDLER}`);
+  tracer.setSegment(handlerSegment);
+
+  // Tracer: Annotate the subsegment with the cold start & serviceName
+  tracer.annotateColdStart();
+  tracer.addServiceNameAnnotation();
+
+  // Tracer: Add annotation for the awsRequestId
+  tracer.putAnnotation('awsRequestId', context.awsRequestId);
+
+  // Metrics: Capture cold start metrics
+  metrics.captureColdStartMetric();
+
+  // All log statements are written to CloudWatch
+  logger.debug('received:', event);
+
+  // Get id and name from the body of the request
+  const body = JSON.parse(event.body!);
+  const id = body.id;
+  const name = body.name;
+
+  // Creates a new item, or replaces an old item with a new item
+  // https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB/DocumentClient.html#put-property
+  const params = {
+    TableName: tableName!,
+    Item: { id: id, name: name }
+  };
+
+  let response;
+
+  try {
+    await docClient.put(params).promise();
+    response = {
+      statusCode: 200,
+      body: JSON.stringify(body)
+    };
+  } catch (err) {
+    tracer.addErrorAsMetadata(err as Error);
+    logger.error('Error writing data to table. ' + err);
+    response = {
+      statusCode: 500,
+      body: JSON.stringify({ 'error': 'Error writing data to table.' })
+    };
+  }
+
+  // Tracer: Close subsegment (the AWS Lambda one is closed automatically)
+  handlerSegment.close(); // (## index.handler)
+
+  // Tracer: Set the facade segment as active again (the one created by AWS Lambda)
+  tracer.setSegment(segment);
+
+  // All log statements are written to CloudWatch
+  logger.info(`response from: ${event.path} statusCode: ${response.statusCode} body: ${response.body}`);
+
+  return response;
+};

examples/lambda-functions/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+      "experimentalDecorators": true,
+      "noImplicitAny": true,
+      "target": "ES2020",
+      "module": "commonjs",
+      "declaration": true,
+      "declarationMap": true,
+      "outDir": "lib",
+      "removeComments": false,
+      "strict": true,
+      "inlineSourceMap": true,
+      "moduleResolution": "node",
+      "resolveJsonModule": true,
+      "pretty": true,
+      "esModuleInterop": true
+  },
+  "exclude": [ "./node_modules"],
+  "watchOptions": {
+      "watchFile": "useFsEvents",
+      "watchDirectory": "useFsEvents",
+      "fallbackPolling": "dynamicPriority"
+  },
+  "lib": [ "es2020" ],
+  "types": [
+      "node"
+  ]
+}