JavaScript (v3): Task - Cleanup nodegetstarted

javascriptv3/example_code/nodegetstarted/README.md

@@ -1,34 +1,64 @@
-# 'Node Getting Started' JavaScript SDK v3 code examples
+# Getting started in Node.js
 
-## Code examples
-This is a workspace where you can find the following AWS SDK for JavaScript version 3 (v3) 'Node Get Started' examples. 
-- Getting started using node.js with the AWS SDK for JavaScript. See [documentation](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started-nodejs.html).
+This guide shows you how to initialize an NPM package, add a service client to your package, and use the JavaScript SDK to call a service action.
 
-**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-example-javascript-syntax.html).
+## ⚠ Important
 
-# Getting started
+- Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/?aws-products-pricing.sort-by=item.additionalFields.productNameLowercase&aws-products-pricing.sort-order=asc&awsf.Free%20Tier%20Type=*all&awsf.tech-category=*all) and [Free Tier](https://aws.amazon.com/free/?all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all).
 
-1. Clone the [AWS SDK 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.
+## Scenario
 
-2. Install the dependencies listed in the package.json.
+Create a new NPM package with one main file that does the following:
 
-**Note**: These include the client module for the AWS services required in these example, 
-which is *@aws-sdk/client-s3*.
-```
-npm install node -g
-cd javascriptv3/example_code/nodegetstarted
-npm install
-```
-3. In your text editor, update user variables specified in the ```Inputs``` section of the sample file.
+- Creates an Amazon S3 bucket.
+- Puts an object in that bucket.
+- Reads that object.
+- Confirms if the user wants to delete resources.
 
-4. Run sample code:
-```
-cd src
-node [example name].js // For example, node sample.js
+### Prerequisites
+
+Before you can run the example, you must complete the following:
+
+- Configure your [SDK authentication](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-your-credentials.html).
+- [Install Node.js](https://nodejs.org/en/download).
+
+### Step 1: Set up the package structure
+
+1. Create a new folder to contain the package.
+2. From the command line, navigate to the new folder.
+3. Run `npm init -y`. This will create a default `package.json`.
+4. Add `"type": "module"` to the `package.json`. This tells Node we're using modern ESM syntax.
+
+The final package.json will look something like this:
+
+```json
+{
+  "name": "example-javascriptv3-get-started-node",
+  "version": "1.0.0",
+  "description": "This guide shows you how to initialize an NPM package, add a service client to your package, and use the JavaScript SDK to call a service action.",
+  "main": "index.js",
+  "scripts": {
+    "test": "vitest run **/*.unit.test.js"
+  },
+  "author": "Corey Pyle <[email protected]>",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.420.0"
+  },
+  "type": "module"
+}
 ```
 
-## Resources
-- [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3) 
-- [AWS documentation for this example](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started-nodejs.html)
+### Step 2: Install the Amazon S3 client package
+
+1. Run `npm i @aws-sdk/client-s3`.
+
+### Step 3: Add necessary imports and SDK code
+
+1. Refer to [index.js](./index.js).
+
+### Step 4: Run the example
 
+1. `node index.js`
+2. Choose whether or not to empty and delete the bucket.
+3. If you choose not to delete the bucket, be sure to empty it and delete it manually.

javascriptv3/example_code/nodegetstarted/index.js

@@ -0,0 +1,94 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// snippet-start:[GettingStarted.JavaScript.NodeJS.sampleV3]
+// This is used for getting user input.
+import { createInterface } from "readline/promises";
+
+import {
+  S3Client,
+  PutObjectCommand,
+  CreateBucketCommand,
+  DeleteObjectCommand,
+  DeleteBucketCommand,
+  paginateListObjectsV2,
+  GetObjectCommand,
+} from "@aws-sdk/client-s3";
+
+export async function main() {
+  // A region and credentials can be declared explicitly. For example
+  // `new S3Client({ region: 'us-east-1', credentials: {...} })` would
+  //initialize the client with those settings. However, the SDK will
+  // use your local configuration and credentials if those properties
+  // are not defined here.
+  const s3Client = new S3Client({});
+
+  // Create an Amazon S3 bucket. The epoch timestamp is appended
+  // to the name to make it unique.
+  const bucketName = `test-bucket-${Date.now()}`;
+  await s3Client.send(
+    new CreateBucketCommand({
+      Bucket: bucketName,
+    })
+  );
+
+  // Put an object into an Amazon S3 bucket.
+  await s3Client.send(
+    new PutObjectCommand({
+      Bucket: bucketName,
+      Key: "my-first-object.txt",
+      Body: "Hello JavaScript SDK!",
+    })
+  );
+
+  // Read the object.
+  const { Body } = await s3Client.send(
+    new GetObjectCommand({
+      Bucket: bucketName,
+      Key: "my-first-object.txt",
+    })
+  );
+
+  console.log(await Body.transformToString());
+
+  // Confirm resource deletion.
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const result = await prompt.question("Empty and delete bucket? (y/n) ");
+  prompt.close();
+
+  if (result === "y") {
+    // Create an async iterator over lists of objects in a bucket.
+    const paginator = paginateListObjectsV2(
+      { client: s3Client },
+      { Bucket: bucketName }
+    );
+    for await (const page of paginator) {
+      const objects = page.Contents;
+      if (objects) {
+        // For every object in each page, delete it.
+        for (const object of objects) {
+          await s3Client.send(
+            new DeleteObjectCommand({ Bucket: bucketName, Key: object.Key })
+          );
+        }
+      }
+    }
+
+    // Once all the objects are gone, the bucket can be deleted.
+    await s3Client.send(new DeleteBucketCommand({ Bucket: bucketName }));
+  }
+}
+
+// Call a function if this file was run directly. This allows the file
+// to be runnable without running on import.
+import { fileURLToPath } from "url";
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main();
+}
+// snippet-start:[GettingStarted.JavaScript.NodeJS.sampleV3]

javascriptv3/example_code/nodegetstarted/package.json

@@ -1,13 +1,18 @@
 {
-  "name": "aws-sdk-v3-iam-examples",
+  "name": "example-javascriptv3-get-started-node",
   "version": "1.0.0",
+  "description": "This guide shows you how to initialize an NPM package, add a service client to your package, and use the JavaScript SDK to call a service action.",
   "main": "index.js",
+  "scripts": {
+    "integration-test": "vitest run **/*.integration.test.js"
+  },
+  "author": "Corey Pyle <[email protected]>",
+  "license": "Apache-2.0",
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.32.0",
-    "@aws-sdk/types": "^3.32.0"
+    "@aws-sdk/client-s3": "^3.420.0"
   },
+  "type": "module",
   "devDependencies": {
-    "@types/node": "^14.0.23"
-  },
-  "type": "module"
+    "vitest": "^0.34.5"
+  }
 }

javascriptv3/example_code/nodegetstarted/tests/index.integration.test.js

@@ -0,0 +1,17 @@
+import { test, vi } from "vitest";
+import { main } from "../index.js";
+
+vi.mock("readline/promises", () => {
+  return {
+    createInterface: () => {
+      return {
+        question: vi.fn(() => Promise.resolve("y")),
+        close: vi.fn(),
+      };
+    },
+  };
+});
+
+test("getting started example should run", async () => {
+  await main();
+});