Stedi SDK for JavaScript

The Stedi SDK for JavaScript enables you to easily work with Stedi, and with a modular architecture with a separate package for each service. It also includes many features, such as a first-class TypeScript support and a new middleware stack.

To get started with JavaScript SDK, visit our SDK API Reference.

To test your universal JavaScript code in Node.js, browser and react-native environments, visit our collection of open-source repositories Stedi Demos.

Getting Started
Features
High Level Concepts
Install from Source
Giving feedback and contributing

Getting Started

Let’s walk through setting up a project that depends on Stash 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.

Create a new Node.js project.
Inside of the project, run: npm add @stedi/sdk-client-stash. Adding packages results in update in lock file, package-lock.json. You should commit your lock file along with your code to avoid potential breaking changes.
Create a new file called index.js, create a Stash service client and send a request.

const { StashClient, ListKeyspacesCommand } = require("@stedi/sdk-client-stash");

(async () => {
  const client = new StashClient({ region: "us" });
  const command = new ListKeyspacesCommand({});
  try {
    const results = await client.send(command);
    console.log(results.items.join("\n"));
  } catch (err) {
    console.error(err);
  }
})();

If you are consuming modular Stedi SDK for JavaScript on react-native environments, you will need to add and import following polyfills in your react-native application:

import "react-native-get-random-values";
import "react-native-url-polyfill/auto";
import { Stash } from "@stedi/sdk-client-stash";

Features

Modularized packages

The SDK is split up across multiple packages. 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.

API changes

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 big changes included in the new Stedi SDK for JavaScript.

Configuration

There is no global configuration managed by the SDK. Configuration must be passed to each service client that is instantiated. It is still possible to share the same configuration across multiple clients but that configuration will not be automatically merged with a global state.

Middleware

We are using a middleware stack to control the lifecycle of an operation call. This gives us a few benefits. Each middleware in the stack calls the next middleware after making any changes to the request object. 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. Here’s an example of adding a custom header using middleware:

const client = new Stash({ region: "us" });
client.middlewareStack.add(
  (next, context) => (args) => {
    args.request.headers["Custom-Header"] = "value";
    console.log("\n -- printed from inside middleware -- \n");
    return next(args);
  },
  {
    step: "build",
  }
);
await client.ListKeyspaces({});

In the above example, we’re adding a middleware to our Stash client’s middleware stack. 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. 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.

Install from Source

All clients have been published to NPM and can be installed as described above. If you want to play with latest clients, you can build from source as follows:

Clone this repository to local by:

git clone https://github.com/Stedi/stedi-sdk-javascript.git

Under the repository root directory, run following command to link and build the whole library, the process may take several minutes:
```
npm install && npm run test:all
```

For more information, please refer to contributing guide.

After the repository is successfully built, change directory to the client that you want to install, for example:
```
cd clients/stash
```
Pack the client:
```
npm pack .
```
npm pack will create an archive file in the client package folder, e.g. stedi-sdk-client-stash-v1.0.0.tgz.
Change directory to the project you are working on and move the archive to the location to store the vendor packages:
```
mv path/to/stedi-sdk-javascript/clients/stash/stedi-sdk-client-stash-v1.0.0.tgz ./path/to/vendors/folder
```

Install the package to your project:

npm add ./path/to/vendors/folder/stedi-sdk-client-stash-v1.0.0.tgz

Giving feedback and contributing

You can provide feedback to us in several ways. Both positive and negative feedback is appreciated. If you do, please feel free to open an issue on our GitHub repository.

Feedback

GitHub issues. Customers who are comfortable giving public feedback can open a GitHub issue in the new repository. This is the preferred mechanism to give feedback so that other customers can engage in the conversation, +1 issues, etc. Issues you open will be evaluated, and included in our roadmap for the GA launch.

Contributing

You can open pull requests for fixes or additions to the new Stedi SDK for JavaScript. All pull requests must be submitted under the Apache 2.0 license and will be reviewed by an SDK team member prior to merging. Accompanying unit tests are appreciated. See Contributing for more information.

High Level Concepts

This is an introduction to some of the high level concepts behind Stedi SDK for JavaScript which are shared between services and might make your life easier. Please consult the user guide and API reference for service specific details.

Terminology:

Bare-bones clients/commands: This refers to a modular way of consuming individual operations on JS SDK clients. It results in less code being imported and thus more performant. It is otherwise equivalent to the aggregated clients/commands.

// this imports a bare-bones version of Buckets that exposes the .send operation
import { BucketsClient } from "@stedi/sdk-client-buckets"

// this imports just the getObject operation from Buckets
import { GetObjectCommand } from "@stedi/sdk-client-buckets"

//usage
const bareBonesBuckets = new BucketsClient({...});
await bareBonesBuckets.send(new GetObjectCommand({...}));

Aggregated clients/commands: This refers to a way of consuming clients that contain all operations on them. Under the hood this calls the bare-bones commands. This imports all commands on a particular client and results in more code being imported and thus less performant.

// this imports an aggregated version of Buckets that exposes the .send operation
import { Buckets } from "@stedi/sdk-client-buckets"

// No need to import an operation as all operations are already on the Buckets prototype

//usage
const aggregatedBuckets = new Buckets({...});
await aggregatedBuckets.getObject({...}));

Generated Code

The codebase is generated from internal models that Stedi services expose. We use smithy-typescript to generate all code in the /clients subdirectory. These packages always have a prefix of @stedi/sdk-client-XXXX and are one-to-one with Stedi services and service operations. You should be importing @stedi/sdk-client-XXXX for most usage.

Clients depend on common "utility" code in /packages. The code in /packages is manually written and outside of special cases (like credentials or abort controller) is generally not very useful alone.

Lastly we have higher level libraries in /lib. These are javascript specific libraries that wrap client operations to make them easier to work with.

/packages. This sub directory is where most manual code updates are done. These are published to NPM under @stedi/sdk-XXXX and have no special prefix.
/clients. This sub directory is code generated and depends on code published from /packages . It is 1:1 with Stedi services and operations. Manual edits should generally not occur here. These are published to NPM under @stedi/sdk-client-XXXX.
/lib. This sub directory depends on generated code published from /clients. It wraps existing Stedi services and operations to make them easier to work with in Javascript. These are published to NPM under @stedi/sdk-lib-XXXX

Paginators

Many Stedi operations return paginated results when the response object is too large to return in a single response. In Stedi SDK for JavaScript, the response contains a token you can use to retrieve the next page of results. You then need to write additional functions to process pages of results.

In Stedi SDK for JavaScript we’ve improved pagination using async generator functions, which are similar to generator functions, with the following differences:

When called, async generator functions return an object, an async generator whose methods (next, throw, and return) return promises for { value, done }, instead of directly returning { value, done }. This automatically makes the returned async generator objects async iterators.
await expressions and for await (x of y) statements are allowed.
The behavior of yield* is modified to support delegation to async iterables.

The Async Iterators were added in the ES2018 iteration of JavaScript. They are supported by Node.js 10.x+ and by all modern browsers, including Chrome 63+, Firefox 57+, Safari 11.1+, and Edge 79+. If you’re using TypeScript v2.3+, you can compile Async Iterators to older versions of JavaScript.

An async iterator is much like an iterator, except that its next() method returns a promise for a { value, done } pair. As an implicit aspect of the Async Iteration protocol, the next promise is not requested until the previous one resolves. This is a simple, yet a very powerful pattern.

Example Pagination Usage

The clients expose paginateOperationName APIs that are written using async generators, allowing you to use async iterators in a for await..of loop. You can perform the paginateListKeyspaces operation from @stedi/sdk-client-stash as follows:

const {
  StashClient,
  paginateListKeyspaces,
} = require("@stedi/sdk-client-stash");

...
const paginatorConfig = {
  client: new StashClient({}),
  pageSize: 25
};
const commandParams = {};
const paginator = paginateListKeyspaces(paginatorConfig, commandParams);

const keyspaces = [];
for await (const page of paginator) {
  // page contains a single paginated output.
  keyspaces.push(...page.items);
}
...

Or simplified:

...
const client = new StashClient({});

const keyspaces = [];
for await (const page of paginateListKeyspaces({ client }, {})) {
    // page contains a single paginated output.
    keyspaces.push(...page.TableNames);
}
...

Abort Controller

We support the AbortController interface which allows you to abort requests as and when desired.

The AbortController Interface provides an abort() method that toggles the state of a corresponding AbortSignal object. Most APIs accept an AbortSignal object, and respond to abort() by rejecting any unsettled promise with an “AbortError”.

// Returns a new controller whose signal is set to a newly created AbortSignal object.
const controller = new AbortController();

// Returns the AbortSignal object associated with controller.
const signal = controller.signal;

// Invoking this method will set controller’s AbortSignal's aborted flag
// and signal to any observers that the associated activity is to be aborted.
controller.abort();

AbortController Usage

In JavaScript SDK, we added an implementation of WHATWG AbortController interface in @aws-sdk/abort-controller. To use it, you need to send AbortController.signal as abortSignal in the httpOptions parameter when calling .send() operation on the client as follows:

const { AbortController } = require("@aws-sdk/abort-controller");
const { BucketsClient, CreateBucketCommand } = require("@stedi/sdk-client-buckets");

...

const abortController = new AbortController();
const client = new BucketsClient(clientParams);

const requestPromise = client.send(new CreateBucketCommand(commandParams), {
  abortSignal: abortController.signal,
});

// The abortController can be aborted any time.
// The request will not be created if abortSignal is already aborted.
// The request will be destroyed if abortSignal is aborted before response is returned.
abortController.abort();

// This will fail with "AbortError" as abortSignal is aborted.
await requestPromise;

For a full pagination deep dive, read this blog post.

AbortController Example

The following code snippet shows how to upload a file using Buckets's putObject API in the browser with support to abort the upload. First, create a controller using the AbortController() constructor, then grab a reference to its associated AbortSignal object using the AbortController.signal property. When the PutObjectCommand is called with .send() operation, pass in AbortController.signal as abortSignal in the httpOptions parameter. This will allow you to abort the PutObject operation by calling abortController.abort().

const abortController = new AbortController();
const abortSignal = abortController.signal;

const uploadBtn = document.querySelector('.upload');
const abortBtn = document.querySelector('.abort');

uploadBtn.addEventListener('click', uploadObject);

abortBtn.addEventListener('click', function() {
  abortController.abort();
  console.log('Upload aborted');
});

const uploadObject = async (file) => {
  ...
  const client = new BucketsClient(clientParams);
  try {
    await client.send(new PutObjectCommand(commandParams), { abortSignal });
  } catch(e) {
    if (e.name === "AbortError") {
      uploadProgress.textContent = 'Upload aborted: ' + e.message;
    }
    ...
  }
}

For a full abort controller deep dive, read this blog post.

Middleware Stack

The JavaScript SDK maintains a series of asynchronous actions. These series include actions that serialize input parameters into the data over the wire and deserialize response data into JavaScript objects. Such actions are implemented using functions called middleware and executed in a specific order. The object that hosts all the middleware including the ordering information is called a Middleware Stack. You can add your custom actions to the SDK and/or remove the default ones.

When an API call is made, SDK sorts the middleware according to the step it belongs to and its priority within each step. The input parameters pass through each middleware. An HTTP request gets created and updated along the process. The HTTP Handler sends a request to the service, and receives a response. A response object is passed back through the same middleware stack in reverse, and is deserialized into a JavaScript object.

A middleware is a higher-order function that transfers user input and/or HTTP request, then delegates to “next” middleware. It also transfers the result from “next” middleware. A middleware function also has access to context parameter, which optionally contains data to be shared across middleware.

For example, you can use middleware to add a custom header like Buckets object metadata:

const { Buckets } = require("@stedi/sdk-client-buckets");
const client = new Buckets({ region: "us" });
// Middleware added to client, applies to all commands.
client.middlewareStack.add(
  (next, context) => async (args) => {
    args.request.headers["x-amz-meta-foo"] = "bar";
    const result = await next(args);
    // result.response contains data returned from next middleware.
    return result;
  },
  {
    step: "build",
    name: "addFooMetadataMiddleware",
    tags: ["METADATA", "FOO"],
  }
);

await client.putObject(params);

Specifying the absolute location of your middleware The example above adds middleware to build step of middleware stack. The middleware stack contains five steps to manage a request’s lifecycle:

The initialize lifecycle step initializes an API call. This step typically adds default input values to a command. The HTTP request has not yet been constructed.
The serialize lifecycle step constructs an HTTP request for the API call. Example of typical serialization tasks include input validation and building an HTTP request from user input. The downstream middleware will have access to serialized HTTP request object in callback’s parameter args.request.
The build lifecycle step builds on top of serialized HTTP request. Examples of typical build tasks include injecting HTTP headers that describe a stable aspect of the request, such as Content-Length or a body checksum. Any request alterations will be applied to all retries.
The finalizeRequest lifecycle step prepares the request to be sent over the wire. The request in this stage is semantically complete and should therefore only be altered to match the recipient’s expectations. Examples of typical finalization tasks include request signing, performing retries and injecting hop-by-hop headers.
The deserialize lifecycle step deserializes the raw response object to a structured response. The upstream middleware have access to deserialized data in next callbacks return value: result.output. Each middleware must be added to a specific step. By default each middleware in the same step has undifferentiated order. In some cases, you might want to execute a middleware before or after another middleware in the same step. You can achieve it by specifying its priority.

client.middlewareStack.add(middleware, {
  step: "initialize",
  priority: "high", // or "low".
});

For a full middleware stack deep dive, read this blog post.