Introduce AWS SDK code snippets for JS and TS

Snippets are "compiled" from their source JS files
along with additional metadata files

Snippet names have the form `aws.<service>.<operation>`
to mimic the SDK invocations

Adds DynamoDB snippets from the API / SDK documentation
https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html

.gitignore

@@ -17,6 +17,9 @@ src/**/*.gen.ts
 # Telemetry definition for testing adding telemetry
 src/shared/telemetry/vscodeTelemetry.json
 
+# Generated snippets
+snippets/out
+
 # Test reports
 .test-reports/
 

build-scripts/copyNonCodeFiles.js

@@ -15,15 +15,16 @@ const outRoot = path.join(repoRoot, 'dist')
 const relativePaths = [
     path.join('src', 'templates'),
     path.join('src', 'test', 'shared', 'cloudformation', 'yaml'),
-    path.join('src', 'integrationTest-samples')
+    path.join('src', 'integrationTest-samples'),
+    path.join('snippets', 'out', 'snippets.json'),
 ]
 
 ;(async () => {
     for (const relativePath of relativePaths) {
         await fs.copy(path.join(repoRoot, relativePath), path.join(outRoot, relativePath), {
             recursive: true,
             overwrite: true,
-            errorOnExist: false
+            errorOnExist: false,
         })
     }
 })()

build-scripts/generateSnippets.ts

@@ -0,0 +1,48 @@
+/*!
+ * Copyright 2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import * as fs from 'fs-extra'
+import * as glob from 'glob'
+import * as path from 'path'
+
+const root = path.join(__dirname, '..')
+const snippetsDir = path.join(root, 'snippets')
+const snippetsSrcDir = path.join(snippetsDir, 'src')
+const snippetsOutDir = path.join(snippetsDir, 'out')
+
+const snippets: {
+    [name: string]: {
+        prefix: string
+        description: string
+        body: string[]
+    }
+} = {}
+
+const directories = new Set(glob.sync(`${snippetsDir}/src/**/body.js`).map(body => path.dirname(body)))
+
+for (const directory of directories) {
+    const metadata = fs.readJSONSync(`${directory}/metadata.json`)
+    const prefix = metadata['prefix']
+    const description = metadata['description']
+    const content = fs.readFileSync(`${directory}/body.js`)
+    const body = content
+        .toString()
+        .split('\n')
+        .map(line => line.replace(/\s?\/\*(?<tabstop>\$\d+)\*\/\s?/g, '$<tabstop>'))
+
+    const name = path
+        .relative(snippetsSrcDir, directory)
+        .split(path.sep)
+        .join('.')
+
+    snippets[name] = {
+        prefix,
+        description,
+        body,
+    }
+}
+
+fs.ensureDirSync(snippetsOutDir)
+fs.writeFileSync(path.join(snippetsOutDir, 'snippets.json'), JSON.stringify(snippets, null, '  '))

package.json

@@ -135,6 +135,16 @@
                 }
             }
         },
+        "snippets": [
+            {
+                "language": "javascript",
+                "path": "./snippets/out/snippets.json"
+            },
+            {
+                "language": "typescript",
+                "path": "./snippets/out/snippets.json"
+            }
+        ],
         "debuggers": [
             {
                 "type": "aws-sam",
@@ -845,7 +855,7 @@
         "compile": "webpack --mode development && npm run buildScripts",
         "recompile": "npm run clean && npm run compile",
         "watch": "npm run buildScripts && tsc -watch -p ./",
-        "postinstall": "ts-node ./build-scripts/generateServiceClient.ts && npm run generateTelemetry && npm run generateConfigurationAttributes",
+        "postinstall": "ts-node ./build-scripts/generateServiceClient.ts && npm run generateTelemetry && npm run generateConfigurationAttributes && npm run generateSnippets",
         "testCompile": "tsc -p ./ && npm run buildScripts",
         "test": "npm run testCompile && ts-node ./test-scripts/test.ts",
         "integrationTest": "npm run testCompile && ts-node ./test-scripts/integrationTest.ts",
@@ -856,6 +866,7 @@
         "install-plugin": "vsce package -o aws-toolkit-vscode-test.vsix && code --install-extension aws-toolkit-vscode-test.vsix",
         "generateTelemetry": "node node_modules/@aws-toolkits/telemetry/lib/generateTelemetry.js --extraInput=src/shared/telemetry/vscodeTelemetry.json --output=src/shared/telemetry/telemetry.gen.ts",
         "generateConfigurationAttributes": "ts-node ./build-scripts/generateConfigurationAttributes.ts",
+        "generateSnippets": "ts-node ./build-scripts/generateSnippets.ts",
         "newChange": "ts-node ./build-scripts/newChange.ts",
         "createRelease": "ts-node ./build-scripts/createRelease.ts"
     },

snippets/.prettierrc.yaml

@@ -0,0 +1 @@
+semi: true

snippets/src/aws/dynamodb/batchGetItem/body.js

@@ -0,0 +1,47 @@
+// To retrieve multiple items from a table
+// This example reads multiple items from the Music table using a batch of three GetItem requests.  Only the AlbumTitle attribute is returned.
+const dynamoDb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
+
+try {
+  const response = await dynamoDb
+    .batchGetItem(
+      /*$0*/ {
+        RequestItems: {
+          Music: {
+            Keys: [
+              {
+                Artist: {
+                  S: "No One You Know"
+                },
+                SongTitle: {
+                  S: "Call Me Today"
+                }
+              },
+              {
+                Artist: {
+                  S: "Acme Band"
+                },
+                SongTitle: {
+                  S: "Happy Day"
+                }
+              },
+              {
+                Artist: {
+                  S: "No One You Know"
+                },
+                SongTitle: {
+                  S: "Scared of My Shadow"
+                }
+              }
+            ],
+            ProjectionExpression: "AlbumTitle"
+          }
+        }
+      }
+    )
+    .promise();
+  console.log(response); // successful response
+} catch (err) {
+  console.log(err, err.stack); // an error occurred
+  throw err;
+}

snippets/src/aws/dynamodb/batchGetItem/metadata.json

@@ -0,0 +1,4 @@
+{
+  "prefix": "aws.dynamodb.batchGetItem",
+  "description": "The BatchGetItem operation returns the attributes of one or more items from one or more tables. You identify requested items by primary key."
+}

snippets/src/aws/dynamodb/batchWriteItem/body.js

@@ -0,0 +1,65 @@
+// To add multiple items to a table
+// This example adds three new items to the Music table using a batch of three PutItem requests.
+const dynamoDb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
+
+try {
+  const response = await dynamoDb
+    .batchWriteItem(
+      /*$0*/ {
+        RequestItems: {
+          Music: [
+            {
+              PutRequest: {
+                Item: {
+                  AlbumTitle: {
+                    S: "Somewhat Famous"
+                  },
+                  Artist: {
+                    S: "No One You Know"
+                  },
+                  SongTitle: {
+                    S: "Call Me Today"
+                  }
+                }
+              }
+            },
+            {
+              PutRequest: {
+                Item: {
+                  AlbumTitle: {
+                    S: "Songs About Life"
+                  },
+                  Artist: {
+                    S: "Acme Band"
+                  },
+                  SongTitle: {
+                    S: "Happy Day"
+                  }
+                }
+              }
+            },
+            {
+              PutRequest: {
+                Item: {
+                  AlbumTitle: {
+                    S: "Blue Sky Blues"
+                  },
+                  Artist: {
+                    S: "No One You Know"
+                  },
+                  SongTitle: {
+                    S: "Scared of My Shadow"
+                  }
+                }
+              }
+            }
+          ]
+        }
+      }
+    )
+    .promise();
+  console.log(response); // successful response
+} catch (err) {
+  console.log(err, err.stack); // an error occurred
+  throw err;
+}

snippets/src/aws/dynamodb/batchWriteItem/metadata.json

@@ -0,0 +1,4 @@
+{
+  "prefix": "aws.dynamodb.batchWriteItem",
+  "description": "The BatchWriteItem operation puts or deletes multiple items in one or more tables. A single call to BatchWriteItem can write up to 16 MB of data, which can comprise as many as 25 put or delete requests. Individual items to be written can be as large as 400 KB."
+}

snippets/src/aws/dynamodb/createTable/body.js

@@ -0,0 +1,41 @@
+// To create a table
+// This example creates a table named Music.
+const dynamoDb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
+
+try {
+  const response = await dynamoDb
+    .createTable(
+      /*$0*/ {
+        AttributeDefinitions: [
+          {
+            AttributeName: "Artist",
+            AttributeType: "S"
+          },
+          {
+            AttributeName: "SongTitle",
+            AttributeType: "S"
+          }
+        ],
+        KeySchema: [
+          {
+            AttributeName: "Artist",
+            KeyType: "HASH"
+          },
+          {
+            AttributeName: "SongTitle",
+            KeyType: "RANGE"
+          }
+        ],
+        ProvisionedThroughput: {
+          ReadCapacityUnits: 5,
+          WriteCapacityUnits: 5
+        },
+        TableName: "Music"
+      }
+    )
+    .promise();
+  console.log(response); // successful response
+} catch (err) {
+  console.log(err, err.stack); // an error occurred
+  throw err;
+}

snippets/src/aws/dynamodb/createTable/metadata.json

@@ -0,0 +1,4 @@
+{
+  "prefix": "aws.dynamodb.createTable",
+  "description": "The CreateTable operation adds a new table to your account. In an AWS account, table names must be unique within each Region. That is, you can have two tables with same name if you create the tables in different Regions."
+}

snippets/src/aws/dynamodb/deleteItem/body.js

@@ -0,0 +1,25 @@
+// To delete an item
+// This example deletes an item from the Music table.
+const dynamoDb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
+
+try {
+  const response = await dynamoDb
+    .deleteItem(
+      /*$0*/ {
+        Key: {
+          Artist: {
+            S: "No One You Know"
+          },
+          SongTitle: {
+            S: "Scared of My Shadow"
+          }
+        },
+        TableName: "Music"
+      }
+    )
+    .promise();
+  console.log(response); // successful response
+} catch (err) {
+  console.log(err, err.stack); // an error occurred
+  throw err;
+}

snippets/src/aws/dynamodb/deleteItem/metadata.json

@@ -0,0 +1,4 @@
+{
+  "prefix": "aws.dynamodb.deleteItem",
+  "description": "Deletes a single item in a table by primary key. You can perform a conditional delete operation that deletes the item if it exists, or if it has an expected attribute value."
+}

snippets/src/aws/dynamodb/deleteTable/body.js

@@ -0,0 +1,17 @@
+// To delete a table
+// This example deletes the Music table.
+const dynamoDb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
+
+try {
+  const response = await dynamoDb
+    .deleteTable(
+      /*$0*/ {
+        TableName: "Music"
+      }
+    )
+    .promise();
+  console.log(response); // successful response
+} catch (err) {
+  console.log(err, err.stack); // an error occurred
+  throw err;
+}

snippets/src/aws/dynamodb/deleteTable/metadata.json

@@ -0,0 +1,4 @@
+{
+  "prefix": "aws.dynamodb.deleteTable",
+  "description": "The DeleteTable operation deletes a table and all of its items. After a DeleteTable request, the specified table is in the DELETING state until DynamoDB completes the deletion. If the table is in the ACTIVE state, you can delete it. If a table is in CREATING or UPDATING states, then DynamoDB returns a ResourceInUseException. If the specified table does not exist, DynamoDB returns a ResourceNotFoundException. If table is already in the DELETING state, no error is returned."
+}

snippets/src/aws/dynamodb/describeLimits/body.js

@@ -0,0 +1,11 @@
+// To determine capacity limits per table and account, in the current AWS region
+// The following example returns the maximum read and write capacity units per table, and for the AWS account, in the current AWS region.
+const dynamoDb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
+
+try {
+  const response = await dynamoDb.describeLimits(/*$0*/ {}).promise();
+  console.log(response); // successful response
+} catch (err) {
+  console.log(err, err.stack); // an error occurred
+  throw err;
+}

snippets/src/aws/dynamodb/describeLimits/metadata.json

@@ -0,0 +1,4 @@
+{
+  "prefix": "aws.dynamodb.describeLimits",
+  "description": "Returns the current provisioned-capacity limits for your AWS account in a Region, both for the Region as a whole and for any one DynamoDB table that you create there."
+}

snippets/src/aws/dynamodb/describeTable/body.js

@@ -0,0 +1,17 @@
+// To describe a table
+// This example describes the Music table.
+const dynamoDb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
+
+try {
+  const response = await dynamoDb
+    .describeTable(
+      /*$0*/ {
+        TableName: "Music"
+      }
+    )
+    .promise();
+  console.log(response); // successful response
+} catch (err) {
+  console.log(err, err.stack); // an error occurred
+  throw err;
+}

snippets/src/aws/dynamodb/describeTable/metadata.json

@@ -0,0 +1,4 @@
+{
+  "prefix": "aws.dynamodb.describeTable",
+  "description": "Returns information about the table, including the current status of the table, when it was created, the primary key schema, and any indexes on the table."
+}