You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The __AWS SDK for JavaScript V3 Developer Preview__ is a rewrite of V2 with some great new features. As with version 2, it enables you to easily work with [Amazon Web Services](https://aws.amazon.com/), but has been written in TypeScript and adds several frequently requested features, like modularized packages.
8
+
The **AWS SDK for JavaScript V3 Developer Preview** is a rewrite of V2 with some great new features. As with version 2, it enables you to easily work with [Amazon Web Services](https://aws.amazon.com/), but has been written in TypeScript and adds several frequently requested features, like modularized packages.
8
9
9
10
Many aspects of the SDK have been refactored and cleaned up, in addition to generating service client packages instead of hydrating services at SDK runtime. The Developer Preview is your chance to influence the direction of the new AWS SDK for JavaScript. Tell us what you like, tell us what you don’t like. Your feedback matters to us.
10
11
11
12
## Production Readiness
13
+
12
14
This project is still in its early stages. We want feedback from you, and may make breaking changes in future releases while the SDK is still in developer preview.
13
15
14
16
The new AWS SDK for JavaScript will also be able to run alongside the version 2.x SDK in the same package to allow partial migration to the new product. As we get close to general availability for version 3, we’ll share a more detailed plan on how we’ll support the 2.x line.
15
17
16
-
17
18
## Getting started
19
+
18
20
Let’s walk through setting up a project that depends on DynamoDB from the SDK and makes a simple service call. The following steps use npm as an example. These steps assume you have node.js and npm already installed.
19
-
1. Create a new node.js project.
20
-
2. Inside of the project, run: `npm install --save @aws-sdk/client-dynamodb-v2-node@preview`
21
-
3. Create a new file called index.js, create a DynamoDB service client and send a request.
21
+
22
+
1. Create a new node.js project.
23
+
2. Inside of the project, run: `npm install --save @aws-sdk/client-dynamodb-v2-node@preview`
24
+
3. Create a new file called index.js, create a DynamoDB service client and send a request.
For users want to use V2-like interfaces, you can import client with only the service name(e.g DynamoDB), and call the operation name directly from the client:
Note that this client is subject to change. It might be removed with SDK V3 comes closer to production-ready.
52
63
53
64
## New features
65
+
54
66
### Modularized packages
67
+
55
68
The SDK is now split up across multiple packages. The 2.x version of the SDK contained support for every service. This made it very easy to use multiple services in a project. Due to the limitations around reducing the size of the SDK when only using a handful of services or operations, many customers requested having separate packages for each service client. We have also split up the core parts of the SDK so that service clients only pull in what they need. For example, a service sends responses in JSON will no longer need to also have an XML parser as a dependency.
56
69
57
70
For those that were already importing services as sub-modules from the version 2.x SDK, the import statement doesn’t look too different. Here’s an example of importing the AWS Lambda service in version 2.0 of the SDK, and the Developer Preview:
71
+
58
72
```javascript
59
73
// import the Lambda client constructor in version 2.0 of the SDK
60
-
constLambda=require('aws-sdk/clients/lambda');
74
+
constLambda=require("aws-sdk/clients/lambda");
61
75
62
76
// import the Lambda client constructor in the node.js version of the Developer Preview
It is also possible to import both versions of the Lambda client by changing the variable name the Lambda constructor is stored in.
66
81
Separate packages for browser and node.js
67
82
@@ -70,53 +85,110 @@ In addition to publishing separate packages for each service client, each packag
70
85
By publishing separate packages for node.js and browser environments, we’ve removed the guesswork around which version your builds will use. This also allows us to use environment-specific typings. For example, streams are implemented with different interfaces in node.js and browsers. Depending on which package you are using, the typings will reflect the streams for the environment you’ve chosen.
71
86
72
87
### API changes
88
+
73
89
We’ve made several public API changes to improve consistency, make the SDK easier to use, and remove deprecated or confusing APIs. The following are some of the bigger changes included in the new AWS SDK for JavaScript Developer Preview.
90
+
74
91
#### Configuration
75
-
In version 2.x of the SDK, service configuration could be passed to individual client constructors.
76
-
However, these configurations would first be merged automatically into a copy of the global SDK configuration: `AWS.config`.
77
-
Also, calling `AWS.config.update({/* params *})` only updated configuration for service clients instantiated after the update call was made, not any existing clients.
92
+
93
+
In version 2.x of the SDK, service configuration could be passed to individual client constructors.
94
+
However, these configurations would first be merged automatically into a copy of the global SDK configuration: `AWS.config`.
95
+
Also, calling `AWS.config.update({/* params *})` only updated configuration for service clients instantiated after the update call was made, not any existing clients.
78
96
79
97
This behavior was a frequent source of confusion, and made it difficult to add configuration to the global object that only affects a subset of service clients in a forward-compatible way.
80
-
In the Developer Preview, there is no longer a global configuration managed by the SDK.
81
-
Configuration must be passed to each service client that is instantiated.
98
+
In the Developer Preview, there is no longer a global configuration managed by the SDK.
99
+
Configuration must be passed to each service client that is instantiated.
82
100
It is still possible to share the same configuration across multiple clients but that configuration will not be automatically merged with a global state.
101
+
83
102
#### Middleware
103
+
84
104
Version 2.x of the SDK allows modifying a request throughout multiple stages of a request’s lifecycle by attaching event listeners to a request.
85
105
Some feedback we received frequently was that it can be difficult to debug what went wrong during a request’s lifecycle.
86
106
We’ve switched to using a middleware stack to control the lifecycle of an operation call now.
87
107
This gives us a few benefits. Each middleware in the stack calls the next middleware after making any changes to the request object.
88
108
This also makes debugging issues in the stack much easier since you can see exactly which middleware have been called leading up to an error.
89
109
Here’s an example of adding a custom header using middleware:
110
+
90
111
```javascript
91
112
lambda.middlewareStack.add(
92
-
(next, context) =>(args)=> {
93
-
args.request.headers['Custom-Header'] ='value';
113
+
(next, context) =>args=> {
114
+
args.request.headers["Custom-Header"] ="value";
94
115
returnnext(args);
95
116
},
96
117
{
97
-
step:'build'
118
+
step:"build"
98
119
}
99
120
);
100
121
101
122
lambda.putObject(params);
102
123
```
103
-
In the above example, we’re adding a middleware to our S3 client’s middleware stack.
104
-
The first argument is a function that accepts next, the next middleware in the stack to call, and context, an object that contains some information about the operation being called.
124
+
125
+
In the above example, we’re adding a middleware to our S3 client’s middleware stack.
126
+
The first argument is a function that accepts next, the next middleware in the stack to call, and context, an object that contains some information about the operation being called.
105
127
It returns a function that accepts args, an object that contains the parameters passed to the operation and the request, and returns the result from calling the next middleware with args.
128
+
129
+
### Install from Source
130
+
131
+
Select clients have been published to NPM and can be installed as described above. For clients that have not yet been published to NPM, follow these instructions to install from source:
0 commit comments