@aws-sdk/config

This package exports dependency implementations for configuring the AWS SDK for JavaScript v3 clients that may be used in your application code.

For an overview of configuration options on SDK clients, see supplemental-docs/CLIENTS.md.

Table of Contents

• Usage
• @aws-sdk/config/credentials
• @aws-sdk/config/logger
• @aws-sdk/config/protocol
• @aws-sdk/config/requestHandler
• @aws-sdk/config/retryStrategy
• @aws-sdk/config/typecheck
  • Compile-time transforms
  • Runtime Typecheck

Usage

Install this alongside your SDK client packages(s) to access optional SDK plugins and injectable dependency implementations.

{
  name: "your-app",
  dependencies: {
    "@aws-sdk/client-s3": "<=3.x.y",
    // where 3.x.y is a version of your choosing.
    "@aws-sdk/client-dynamodb": "<=3.x.y",
    "@aws-sdk/config": "<=3.x.y",
  },
}

The elements exported from this package are organized into submodules accessible by import paths.

@aws-sdk/config/credentials

This module includes the same API exported from @aws-sdk/credential-providers.

// example: credentials
import { fromIni } from "@aws-sdk/config/credentials";

new S3Client({
  credentials: fromIni(),
});

See @aws-sdk/credential-providers for the complete API.

See also CLIENTS.md#credentials.

@aws-sdk/config/logger

This module exports a helper for log level filtering.

// example: logger
import { LogLevel } from "@aws-sdk/config/logger";

new S3Client({
  logger: new LogLevel("debug", console),
});

See CLIENTS.md#logger for implementing your own logger.

@aws-sdk/config/protocol

This module exports a selection of AWS Protocols, which you can use for protocol selection override or extend to customize serialization behavior (advanced usage).

// example: protocol selection.
import { CloudWatchClient } from "@aws-sdk/client-cloudwatch";
import { AwsSmithyRpcV2CborProtocol } from "@aws-sdk/config/protocol";

new CloudWatchClient({
  protocol: AwsSmithyRpcV2CborProtocol,
});

// example: protocol extension.
import { AwsRestXmlProtocol } from "@aws-sdk/config/protocol";

new S3Client({
  protocol: class CustomAwsRestXmlProtocol extends AwsRestXmlProtocol {},
});

See CLIENTS.md#protocol.

@aws-sdk/config/requestHandler

This module exports the two common HTTP request handler implementations for extension.

// example: requestHandler extension.
import { NodeHttpHandler, FetchHttpHandler } from "@aws-sdk/config/requestHandler";

new S3Client({
  requestHandler: new (class extends NodeHttpHandler {
    async handle(request) {
      return super.handle(request);
    }
  })(),
});

See CLIENTS.md#requestHandler.

@aws-sdk/config/retryStrategy

This module exports the SDK retry strategy implementations. Please keep in mind that typically, you won't need to customize the retry behavior of the SDK, and that maxAttempts and retryMode can be configured with simple values that do not need imports.

See CLIENTS.md#retryStrategy.

// example: retryStrategy with custom backoff.
import { ConfiguredRetryStrategy } from "@aws-sdk/config/retryStrategy";

new S3Client({
  retryStrategy: new ConfiguredRetryStrategy(
    // attempts
    5,

    // backoff 1 additional second per attempt
    (attempt: number) => 500 + attempt * 1_000
  ),
});

@aws-sdk/config/typecheck

This module exports compile-time type transform helpers and runtime typechecking components.

Compile-time transforms

For compile-time type transform helpers, see usage at @smithy/types.

// example: type transformers.
import type { AssertiveClient, BrowserClient, NodeJsClient, UncheckedClient } from "@aws-sdk/config/typecheck";

// UncheckedClient makes output fields non-nullable.
// You should still perform type checks as you deem
// necessary, but the SDK will no longer prompt you
// with nullability errors.
const s3 = new S3({}) as UncheckedClient<S3>;

// this transform narrows the type of output streams to Node.js Readable.
const s3Nodejs = new S3Client({}) as NodeJsClient<S3Client>;

// this transform narrows the type of output streams to web ReadableStream.
const s3Browser = new S3Client({}) as BrowserClient<S3Client>;

Runtime Typecheck

Refer to SCHEMAS.md for an introduciton to how the SDK uses schemas to serialize and deserialize data structures. Schemas are also used by the runtime typecheck plugin.

// example: runtime typecheck usage with SDK client
import { DynamoDB } from "@aws-sdk/client-dynamodb";
import { getRuntimeTypecheckPlugin } from "@aws-sdk/config/typecheck";

const ddb = new DynamoDB();

ddb.middlewareStack.use(
  // requires AWS SDK v3.953.0+ for shape checking.
  // requires AWS SDK v3.969.0+ for required member checks.
  getRuntimeTypecheckPlugin({
    logger: console,
    // throw means stop execution,
    // other values correspond to logger channel.
    input: "throw" || "error" || "warn" || "info" || "debug",
  })
);

await ddb
  .getItem({
    Key: {
      id: {
        S: new Date("wrong type"),
      },
    },
  })
  .catch(console.error);

/*
Error: DynamoDBClient->GetItemCommand input validation:
        {}.TableName: is required.
        {}.Key["id"].S: expected string, got object.
<... stack trace ...>
 */

// standalone usage
import { GetItemInput$ } from "@aws-sdk/client-dynamodb";
import { validateSchema } from "@aws-sdk/config/typecheck";

const errors = validateSchema(GetItemInput$, {
  Key: {
    id: {
      S: new Date("wrong type"),
    },
  },
});

console.log(errors.join("\n"));

/*
{}.TableName: is required.
{}.Key["id"].S: expected string, got object.
 */