Update scenario readme (#3835)

brmur · ford-at-aws · irenepsmith · web-flow · commit 268ba2d0f4c2 · 2022-10-19T10:19:25.000-04:00
* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

* updates to dynamodb_basics.js scenario

Co-authored-by: ford prior &lt;108086978+ford-at-aws@users.noreply.github.com&gt;
Co-authored-by: Irene Smith &lt;73654695+irenepsmith@users.noreply.github.com&gt;
diff --git a/javascriptv3/example_code/README.md b/javascriptv3/example_code/README.md
@@ -1,35 +1,52 @@
-# AWS SDK for JavaScript v3 examples
 
-These are examples for the AWS SDK for JavaScript version 3 (v3) public documentation.
+# AWS SDK for JavaScript (v3) code examples
+## Overview
+The code examples in this topic show you how to use the AWS SDK for JavaScript (v3) with AWS.
 
-## Prerequisites
-To build and run these examples, you need to:
+The AWS SDK for JavaScript (v3) provides a JavaScript API for AWS infrastructure services. Using the SDK, you can build applications on top of Amazon S3, Amazon EC2, Amazon DynamoDB, and more.
 
-* Set up the project environment to run these TypeScript examples with Node.js, and install the required AWS SDK for JavaScript and third-party modules. Follow the instructions in the README.md in the folder with the examples you're running; for example, [instructions for Amazon S3 examples](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/javascriptv3/example_code/s3/README.md).
-* Create a shared configurations file with your user credentials. See the [AWS SDK for JavaScript v3 Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html) for more information.
+## Types of code examples
+* **Single-service actions** - Code examples that show you how to call individual service functions.
 
-## Running the examples
-Examples are written for either execution in a browser script or in Node.js, usually depending on the use case for each. The two scenarios typically differ in how you supply credentials to the code. For information on the differences, see the [AWS SDK for JavaScript v3 Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials.html).
+* **Single-service scenarios** - Code examples that show you how to accomplish a specific task by calling multiple functions within the same service.
 
-The Node.js examples are all run from the command line.
+* **Cross-service examples** - Sample applications that work across multiple AWS services.
 
-## Unit tests
-[Unit tests](./tests) are provided for many examples, using the [Jest](https://jestjs.io/) framework.
+### Find code examples
+Single-service actions and scenarios are organized by AWS service in this folder. A README in each folder lists and describes how to run the examples.
 
-To run tests, navigate to the **tests** folder.
+Cross-service examples are located in the [*cross-services folder*](./cross-services). A README in each folder describes how to run the example.
 
-For example, to run tests on the S3 folder, enter the following sequence of commands at the command prompt:
+## ⚠️ Important
+* Running this code might result in charges to your AWS account.
+* Running the tests might result in charges to your AWS account. 
+* We recommend that you grant your code the least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
 
+
+### Prerequisites
+* Latest stable version of Node.js.
+* A shared configuration file with your user credentials. For more information, see the [AWS SDK for JavaScript (v3) Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/loading-node-credentials-shared.html).
+
+## Tests
+**Note**: Running the tests might result in charges to your AWS account.
+
+1. Where tests are provided, navigate to the 'tests' folder located in the root of the service folder.
+
+**Note**: In some cases scenarios and cross-service examples have their own test folder, so navigate to that instead.
+
+2. Run the following:
 ```
-npm install node -g
-cd javascriptv3/example_code/s3/tests
+cd javascriptv3/example_code/[service folder name]
 npm install
 npm test
 ```
-## Resources
-* [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3)
-* [AWS SDK for JavaScript v3 Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/)
-* [AWS SDK for JavaScript v3 API Reference](http://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index.html)
 
-Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
-SPDX-License-Identifier: Apache-2.0
+## Additional resources
+* [AWS SDK for JavaScript (v3)](https://github.com/aws/aws-sdk-js-v3)
+* [AWS SDK for JavaScript (v3) Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/)
+* [AWS SDK for JavaScript (v3) API Reference](http://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index.html)
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0
+
+
diff --git a/javascriptv3/example_code/dynamodb/README.md b/javascriptv3/example_code/dynamodb/README.md
@@ -1,21 +1,27 @@
-# Amazon DynamoDB JavaScript SDK v3 code examples
+# Amazon DynamoDB code examples for AWS SDK for JavaScript (v3)
 The code examples in this directory demonstrate how to work with Amazon DynamoDB using the AWS SDK for JavaScript version 3 (v3).
 
-Amazon DynamoDB is a key-value and document database that delivers single-digit millisecond performance at any scale. It's a fully managed, multiregion, multimaster, durable database with built-in security, backup and restore, and in-memory caching for internet-scale applications. 
+Amazon DynamoDB is a fully managed NoSQL database service that provides fast and predictable performance with seamless scalability. You can use Amazon DynamoDB to create a database table that can store and retrieve any amount of data, and serve any level of request traffic. Amazon DynamoDB automatically spreads the data and traffic for the table over a sufficient number of servers to handle the request capacity specified by the customer and the amount of data stored, while maintaining consistent and fast performance.
+###Table of contents
+- [Important information](#-important-information)
+- [Code examples](#code-examples)
+  - [Single actions](#single-actions)
+  - [Scenarios](#scenarios)
+- [Run the examples](#run-the-examples)
+  - [Prerequisites](#prerequisites)
+  - [Steps](#steps)
+- [Unit tests](#unit-tests)
+- [Additional resources](#-A)
 
-## Code examples
-This is a workspace where you can find the following AWS SDK for JavaScript version 3 (v3) Amazon DynamoDB examples: 
+## ⚠️ Important information
+* Running the tests might result in charges to your AWS account.
+* We recommend that you grant your code the least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
 
-### Scenario examples
+## The code examples
 
-- [DynamoDB_basics](scenarios/dynamodb_basics/src/dynamodb_basics.js)
-
-#### Scenario examples using PartiQL
-
-- [PartiQL_basics](scenarios/partiQL_basics/src/partiQL_basics.js)
-- [PartiQL_batch_basics](scenarios/partiQL_basics/src/partiQL_batch_basics.js)
-
-### API Examples - DynamoDB
+### Single actions
+Code excerpts that show you how to call individual service functions.
 
 - [Create a DynamoDB table](src/ddb_createtable.js) (CreateTableCommand)
 - [Create a DynamoDB table - TV example](src/QueryExample/ddb_createtable_tv.js)
@@ -33,8 +39,6 @@ This is a workspace where you can find the following AWS SDK for JavaScript vers
 - [Update a DynamoDB table using Document Client](src/movies/updateItem.js) (UpdateCommand)
 - [Write batch items using Document Client](src/movies/writeData.js) (BatchGetWriteCommand)
 - [Write batch items - TV example](src/QueryExample/ddb_batchwriteitem_tv.js)
-
-#### API Examples - DynamoDB using PartiQL
 - [Add an item to a table using PartiQL](src/partiQL_examples/src/partiql_putItem.js) (ExecuteStatementCommand)
 - [Add items to a table by batch using PartiQL](src/partiQL_examples/src/partiql_batch_putItems.js) (BatchExecuteStatementCommand)
 - [Delete an item from a table using PartiQL](src/partiQL_examples/src/partiql_deleteItem.js) (ExecuteStatementCommand)
@@ -44,37 +48,35 @@ This is a workspace where you can find the following AWS SDK for JavaScript vers
 - [Update an item in a table using PartiQL](src/partiQL_examples/src/partiql_updateItem.js) (ExecuteStatementCommand)
 - [Update items in a table by batch using PartiQL](src/partiQL_examples/src/partiql_batch_updateItems.js) (BatchExecuteStatementCommand)
 
-**Note**: All code examples are written in ECMAscript 6 (ES6). For guidelines on converting to CommonJS, see 
-[JavaScript ES6/CommonJS syntax](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/sdk-examples-javascript-syntax.html).
 
-## Getting started
+### Scenarios
+Code examples that show you how to accomplish a specific task by calling multiple functions within the same service.
+
+- [DynamoDB basics](scenarios/dynamodb_basics/src/dynamodb_basics.js)
+- [PartiQL basics](scenarios/partiQL_basics/src/partiQL_basics.js)
+- [PartiQL batch_basics](scenarios/partiQL_basics/src/partiQL_batch_basics.js)
+
+## Run the examples
 
-1. Clone the [AWS Code Samples repo](https://github.com/awsdocs/aws-doc-sdk-examples) to your local environment. 
-See [the Github documentation](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) for 
-instructions.
+### Prerequisites
 
-2. Install the dependencies listed in the package.json.
+- [Set up AWS SDK for JavaScript](../README.md#prerequisites)
+
+### Instructions
+
+1. Install the dependencies.
 
-**Note**: These include the client modules for the AWS services required in these example, 
-which are *@aws-sdk/client-dynamodb*, *@aws-sdk/lib-dynamodb*.
 ```
-npm install node -g
 cd javascriptv3/example_code/dynamodb
 npm install
 ```
-3. In your text editor, update user variables specified in the ```Inputs``` section of the sample file.
-
-4. Run sample code:
-```
-cd src
-node [example name].js // For example, node ddb_batchgetitem.js
-```
+2. Follow the instructions at the top of the example.
 
-## Unit tests
-For more information see, the [README](../README.rst).
+## Tests
+For more information, see the [README](../README.md).
 
-## Resources
-- [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) is available. 
-- [AWS SDK for JavaScript v3 Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/dynamodb-examples.html) 
-- [AWS SDK for JavaScript v3 API Reference Guide - Amazon DynamoDB client module](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-dynamodb/index.html) 
+## Additional resources
+- [AWS SDK for JavaScript (v3)](https://github.com/aws/aws-sdk-js-v3) is available. 
+- [AWS SDK for JavaScript (v3) Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/dynamodb-examples.html) 
+- [AWS SDK for JavaScript (v3) API Reference Guide - Amazon DynamoDB client module](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-dynamodb/index.html) 
 
diff --git a/javascriptv3/example_code/dynamodb/package.json b/javascriptv3/example_code/dynamodb/package.json
@@ -1,24 +1,21 @@
 {
-  "name": "aws-sdk-v3-dynamodb-examples",
+  "name": "dynamo_basics",
   "version": "1.0.0",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
   "main": "index.js",
   "repository": "git@github.com/awsdocs/aws-doc-sdk-examples/tree/master/javascriptv3/example_code/iam.git",
-  "author": "Brian Murray <brmur@amazon.com>, Alex Forsyth <alex-git@amazon.com>",
+  "author": "Brian Murray <brmur@amazon.com>",
   "license": "Apache 2.0",
   "scripts": {
     "test": "jest"
   },
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^3.32.0",
-    "@aws-sdk/node-http-handler": "^3.32.0",
     "@aws-sdk/lib-dynamodb": "^3.32.0",
-    "@aws-sdk/types": "^3.32.0",
-    "node-fetch": "^2.6",
+    "ramda": "^0.28.0",
     "jest": "^26.6.3"
   },
-  "devDependencies": {
-    "@types/node": "^14.0.23",
-    "typescript": "^4.0.2"
-  },
   "type": "module"
 }
diff --git a/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/libs/ddbClient.js b/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/libs/ddbClient.js
@@ -8,7 +8,7 @@ Purpose:
 ddbClient.js is a helper function that creates an Amazon Simple Storage Service (Amazon S3) service client.
 
 Inputs (replace in code):
-
+-REGION - replace with your AWS Region.
 */
 // snippet-start:[dynamodb.JavaScript.scenario.basics.createclientv3]
 // Create the DynamoDB service client module using ES6 syntax.
diff --git a/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/libs/ddbDocClient.js b/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/libs/ddbDocClient.js
@@ -6,9 +6,6 @@ which is available at https://github.com/aws/aws-sdk-js-v3.
 Purpose:
 ddbDocClient.js is a helper function that creates an Amazon DynamoDB service document client.
 
-INPUTS:
-- REGION
-
 */
 // snippet-start:[dynamodb.JavaScript.scenario.basics.createdocclientv3]
 
diff --git a/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/package.json b/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/package.json
diff --git a/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/src/dynamodb_basics.js b/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/src/dynamodb_basics.js
@@ -5,7 +5,7 @@ ABOUT THIS NODE.JS EXAMPLE: This example works with the AWS SDK for JavaScript v
 which is available at https://github.com/aws/aws-sdk-js-v3.
 
 Purpose:
-Scenario demonstrating how to:
+This scenario demonstrates how to:
     - Create a table that can hold movie data.
     - Write movie data to the table from a sample JSON file.
     - Put, get, and update a single movie in the table.
@@ -15,11 +15,14 @@ Scenario demonstrating how to:
     - Delete a movie from the table.
     - Delete the table.
 
+
 Running the code:
-node dynamodb_basics.js <table_name> <newMovieName> <newMovieYear> <existingMovieName> <existingMovieYear> <newMovieRank> <newMoviePlot>
+1. Update the AWS Region in '../libs/ddbClient.js'.
+2. Run the following at the command line:
 
-For example, node dynamodb_basics.js myNewTable myMovieName 2022 'This Is the End' 2013 200 'A coder cracks code...'
+   node dynamodb_basics.js <table_name> <newMovieName> <newMovieYear> <existingMovieName> <existingMovieYear> <newMovieRank> <newMoviePlot>
 
+   For example, node dynamodb_basics.js myNewTable myMovieName 2022 'This Is the End' 2013 200 'A coder cracks code...'
 
 // snippet-start:[javascript.dynamodb_scenarios.dynamodb_basics]
 */
@@ -44,7 +47,7 @@ import {
 
 if (process.argv.length < 6) {
   console.log(
-    "Usage: node dynamodb_basics.js <tableNaame> <newMovieName> <newMovieYear> <existingMovieName> <existingMovieYear> <newMovieRank> <newMoviePlot>\n" +
+    "Usage: node dynamodb_basics.js <tableName> <newMovieName> <newMovieYear> <existingMovieName> <existingMovieYear> <newMovieRank> <newMoviePlot>\n" +
       "Example: node dynamodb_basics.js newmoviesbrmur newmoviename 2025 200 'MOVIE PLOT DETAILS'"
   );
 }
@@ -124,10 +127,8 @@ export const run = async (
       await ddbDocClient.send(new PutCommand(params));
       console.log("Success - single movie added.");
       try {
-        // Before you run this example, download 'movies.json' from https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GettingStarted.Js.02.html,
-        // and put it in the same folder as the example.
         // Get the movie data parse to convert into a JSON object.
-        const allMovies = JSON.parse(fs.readFileSync("moviedata.json", "utf8"));
+        const allMovies = JSON.parse(fs.readFileSync("../../../../../../resources/sample_files/movies.json", "utf8"));
         // Split the table into segments of 25.
         const dataSegments = R.splitEvery(25, allMovies);
         // Loop batch write operation 10 times to upload 250 items.
@@ -161,15 +162,15 @@ export const run = async (
             TableName: tableName,
             Key: {
               title: existingMovieName,
-              year: existingMovieYear,
+              year: existingMovieYear
             },
             // Define expressions for the new or updated attributes.
             ProjectionExpression: "#r",
             ExpressionAttributeNames: { "#r": "rank" },
             UpdateExpression: "set info.plot = :p, info.#r = :r",
             ExpressionAttributeValues: {
               ":p": newMoviePlot,
-              ":r": newMovieRank,
+              ":r": newMovieRank
             },
             ReturnValues: "ALL_NEW",
           };
@@ -217,11 +218,10 @@ export const run = async (
                   console.log(
                     "Scan successful. Items with rank of " +
                       newMovieRank +
-                      " include\n" +
-                      "Year = " +
-                      data.Items[i].year +
-                      " Title = " +
-                      data.Items[i].title
+                      " include:\n" +
+                      data.Items[i].title +
+                      ", released in " +
+                      data.Items[i].year
                   );
                 }
                 try {
@@ -248,11 +248,10 @@ export const run = async (
                     console.log(
                       "Query successful. Items with rank of " +
                         newMovieRank +
-                        " include\n" +
-                        "Year = " +
-                        data.Items[i].year +
-                        " Title = " +
-                        data.Items[i].title
+                        " include:\n" +
+                        data.Items[i].title +
+                        ", released in " +
+                        data.Items[i].year
                     );
                   }
                   try {
@@ -273,6 +272,7 @@ export const run = async (
                       const params = {
                         TableName: tableName,
                       };
+                      wait(5000);
                       await ddbDocClient.send(
                         new DeleteTableCommand(params)
                       );
diff --git a/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/tests/dynamodb_basics.test.js b/javascriptv3/example_code/dynamodb/scenarios/dynamodb_basics/tests/dynamodb_basics.test.js
@@ -1,26 +1,22 @@
-var tableName = "dynamodb-scenario-table-name";
-var newMovieName = "new-movie-name";
-var newMovieYear = 2022;
-var existingMovieName = "Rush";
-var existingMovieYear = 2013;
-var newMovieRank = 111;
-var newMoviePlot = "movie-plot";
-
-const expected = "Run successfully";
+process.argv.push("node", "dynamodb_basics.js", "myNewTable", "myMovieName", 2022, "This Is the End", 2013, 200, "A coder cracks code...");
+console.log('argv', process.argv[4], process.argv[5], process.argv[6], process.argv[7], process.argv[8], process.argv[9], process.argv[10]);
 
 import "regenerator-runtime/runtime";
 import { run } from "../src/dynamodb_basics.js";
 jest.setTimeout(50000);
+
+const expected = "Run successfully";
+
 describe("Test function runs", () => {
   it("should successfully run", async () => {
     const response = await run(
-      tableName,
-      newMovieName,
-      newMovieYear,
-      existingMovieName,
-      existingMovieYear,
-      newMovieRank,
-      newMoviePlot
+        process.argv[4],
+        process.argv[5],
+        process.argv[6],
+        process.argv[7],
+        process.argv[8],
+        process.argv[9],
+        process.argv[10]
     );
     console.log("Response ", Promise.resolve(response));
     expect(response).toEqual(expected);
diff --git a/resources/sample_files/movies.json b/resources/sample_files/movies.json
