or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdclient.mddns.mdhttp.mdindex.mdmiddleware.mdserialization.md
tile.json

tessl/npm-aws-sdk--types

TypeScript type definitions and interfaces for the AWS SDK for JavaScript v3

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-sdk/types@3.862.x

To install, run

npx @tessl/cli install tessl/npm-aws-sdk--types@3.862.0

index.mddocs/

AWS SDK Types

AWS SDK Types (@aws-sdk/types) provides comprehensive TypeScript type definitions for the AWS SDK for JavaScript v3. It serves as the foundational type library that defines interfaces, types, and contracts used throughout the entire AWS SDK ecosystem, enabling strong type safety and IntelliSense support for developers building applications with AWS services.

Package Information

  • Package Name: @aws-sdk/types
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @aws-sdk/types

Core Imports

import { 
  AwsCredentialIdentity, 
  AwsCredentialIdentityProvider,
  Logger, 
  HttpRequest, 
  HttpResponse,
  Headers,
  Client,
  Command,
  Provider,
  MetadataBearer,
  HostAddressType,
  HostResolver
} from "@aws-sdk/types";

For CommonJS:

const { 
  AwsCredentialIdentity, 
  AwsCredentialIdentityProvider,
  Logger, 
  HttpRequest, 
  HttpResponse,
  Headers,
  Client,
  Command,
  Provider,
  MetadataBearer,
  HostAddressType,
  HostResolver
} = require("@aws-sdk/types");

Basic Usage

import { 
  AwsCredentialIdentity, 
  AwsCredentialIdentityProvider,
  Logger, 
  HttpRequest, 
  Headers,
  Provider,
  MetadataBearer
} from "@aws-sdk/types";

// Define AWS credentials
const credentials: AwsCredentialIdentity = {
  accessKeyId: "your-access-key",
  secretAccessKey: "your-secret-key",
  sessionToken: "optional-session-token"
};

// Create a credential provider
const credentialProvider: AwsCredentialIdentityProvider = async () => credentials;

// Configure logger
const logger: Logger = {
  trace: (message: string) => console.trace(message),
  debug: (message: string) => console.debug(message),
  info: (message: string) => console.info(message),
  warn: (message: string) => console.warn(message),
  error: (message: string) => console.error(message)
};

// Use HTTP types for request/response handling
const request: HttpRequest = {
  method: "GET",
  protocol: "https:",
  hostname: "s3.amazonaws.com",
  path: "/my-bucket/my-object",
  headers: new Map([["Authorization", "AWS4-HMAC-SHA256 ..."]])
};

// Working with AWS-specific Headers interface
declare const headers: Headers;
const modifiedHeaders = headers
  .withHeader("Content-Type", "application/json")
  .withoutHeader("User-Agent");

Architecture

The @aws-sdk/types package is organized around several key architectural components:

  • Core Type System: Re-exports comprehensive types from @smithy/types providing the foundation for HTTP, middleware, authentication, and serialization
  • AWS Extensions: AWS-specific type definitions that extend base Smithy types with AWS service patterns and conventions
  • Identity Management: Complete authentication and authorization type definitions including credentials, tokens, and various identity providers
  • Request/Response Pipeline: Types for HTTP handling, middleware execution, and request/response processing chains
  • Service Integration: Common patterns and interfaces used across all AWS service clients for consistent API design

Capabilities

Authentication & Identity

Complete type definitions for AWS authentication mechanisms including credentials, identity providers, and authentication schemes. Essential for all AWS service interactions.

interface AwsCredentialIdentity {
  readonly accessKeyId: string;
  readonly secretAccessKey: string;
  readonly sessionToken?: string;
  readonly expiration?: Date;
  readonly credentialScope?: string;
  readonly accountId?: string;
}

type AwsCredentialIdentityProvider = Provider<AwsCredentialIdentity>;

Authentication & Identity

HTTP Request & Response

Core HTTP types for request construction, response handling, and header management used throughout the AWS SDK ecosystem.

interface HttpRequest extends HttpMessage {
  method: string;
  protocol: string;
  hostname: string;
  port?: number;
  path: string;
  query?: QueryParameterBag;
}

interface HttpResponse extends HttpMessage {
  statusCode: number;
  reason?: string;
}

interface Headers extends Map<string, string> {
  withHeader(headerName: string, headerValue: string): Headers;
  withoutHeader(headerName: string): Headers;
}

HTTP Request & Response

Middleware & Request Processing

Middleware stack types for request/response processing, handler execution, and plugin architecture that powers the AWS SDK's extensible pipeline.

interface AwsHandlerExecutionContext extends HandlerExecutionContext {
  __aws_sdk_context?: {
    features?: AwsSdkFeatures;
  };
}

interface MiddlewareStack<Input, Output> {
  add<T>(middleware: Middleware<Input, Output, T>, options?: MiddlewareOptions): void;
  resolve<T>(handler: Handler<Input, Output>, context: T): Handler<Input, Output>;
}

Middleware & Request Processing

Service Client Architecture

Base types for AWS service clients, commands, and the command pattern used throughout the SDK for consistent service interaction.

interface Client<Input, Output, ResolvedClientConfiguration> {
  readonly config: ResolvedClientConfiguration;
  send<InputType, OutputType>(
    command: Command<InputType, OutputType, Input, Output>,
    options?: any
  ): Promise<OutputType>;
  destroy(): void;
}

interface Command<Input, Output, ClientInput = Input, ClientOutput = Output> {
  readonly input: Input;
  resolveMiddleware(
    stack: MiddlewareStack<ClientInput, ClientOutput>,
    configuration: any,
    options: any
  ): Handler<Input, Output>;
}

Service Client Architecture

DNS Resolution & Networking

AWS-specific DNS resolution and networking types for advanced connection management and multi-region scenarios.

enum HostAddressType {
  AAAA = "AAAA", // IPv6
  A = "A"        // IPv4
}

interface HostResolver {
  resolveAddress(args: HostResolverArguments): Promise<HostAddress[]>;
  reportFailureOnAddress(addr: HostAddress): void;
  purgeCache(args?: HostResolverArguments): void;
}

DNS Resolution & Networking

Serialization & Data Processing

Types for data serialization, deserialization, encoding, and streaming used for processing AWS service requests and responses.

interface SerdeContext {
  base64Encoder?: Encoder;
  base64Decoder?: Decoder;
  utf8Encoder?: Encoder;
  utf8Decoder?: Decoder;
  streamCollector?: StreamCollector;
  logger?: Logger;
}

interface ResponseDeserializer<OutputType, ResponseType = HttpResponse> {
  deserialize(
    response: ResponseType,
    options: DeserializeHandlerOptions & SerdeContext
  ): Promise<OutputType>;
}

Serialization & Data Processing

Additional Type Categories

Core Utility Types

General-purpose types used throughout the AWS SDK ecosystem, available from this package but primarily defined in @smithy/types.

// Provider pattern for dynamic value resolution
type Provider<T> = T | (() => T) | (() => Promise<T>);

// Memoized provider for caching resolved values
interface MemoizedProvider<T> {
  (): Promise<T>;
  isMemoized: true;
}

// Response metadata interface
interface MetadataBearer {
  $metadata: ResponseMetadata;
}

interface ResponseMetadata {
  httpStatusCode?: number;
  requestId?: string;
  extendedRequestId?: string;
  cfId?: string;
  attempts?: number;
  totalRetryDelay?: number;
}

// User agent types for client identification
type UserAgentPair = [string, string | undefined];
type UserAgent = UserAgentPair[];

// Body length calculator for request size determination
type BodyLengthCalculator = (body: any) => number;

// URL parser for endpoint handling
interface UrlParser {
  (url: string): URL;
}

// Encoder/Decoder for data transformation
interface Encoder {
  (input: string): Uint8Array;
}

interface Decoder {
  (input: Uint8Array): string;
}

Event Streaming

Event stream types are available for real-time AWS services (re-exported from @smithy/types).

interface Message {
  headers: MessageHeaders;
  body: Uint8Array;
}

interface EventStreamMarshaller {
  marshall(message: any): Uint8Array;
  unmarshall(data: Uint8Array): any;
}

Request Signing & Cryptography

Request signing and cryptographic types (re-exported from @smithy/types).

interface RequestSigner {
  sign(request: HttpRequest, options?: RequestSigningArguments): Promise<HttpRequest>;
}

interface Hash {
  update(data: Uint8Array): void;
  digest(): Promise<Uint8Array>;
}

Error Handling & Retry Logic

Error handling and retry strategy types (re-exported from @smithy/types).

interface RetryStrategyV2 {
  acquireInitialRetryToken(retryTokenScope: string): Promise<RetryToken>;
  refreshRetryTokenForRetry(token: RetryToken, errorInfo: RetryErrorInfo): Promise<RetryToken>;
  recordSuccess(token: RetryToken): void;
}

interface SdkError extends Error {
  readonly name: string;
  readonly $fault: "client" | "server";
  readonly $service?: string;
  readonly $retryable?: RetryableTrait;
}

Logging Configuration

Logging interfaces and AWS-specific log level configuration.

interface Logger {
  trace?: (message: any, ...optionalParams: any[]) => void;
  debug?: (message: any, ...optionalParams: any[]) => void;
  info?: (message: any, ...optionalParams: any[]) => void;
  warn?: (message: any, ...optionalParams: any[]) => void;
  error?: (message: any, ...optionalParams: any[]) => void;
}

type LogLevel = "all" | "trace" | "debug" | "log" | "info" | "warn" | "error" | "off";

interface LoggerOptions {
  logger?: Logger;
  logLevel?: LogLevel;
}

AWS-Specific Internal Types

// Internal AWS configuration types
interface CredentialProviderOptions {
  logger?: Logger;
  parentClientConfig?: {
    region?: string | Provider<string>;
    profile?: string;
    [key: string]: unknown;
  };
}

// AWS SDK feature tracking (internal)
type AwsSdkFeatures = Partial<{
  [key: string]: string;
}>;

// Function composition utility
type MergeFunctions<F1, F2> = F1 extends (arg: infer A1) => infer R1
  ? F2 extends (arg: infer A2) => infer R2
    ? R1 extends Promise<unknown>
      ? (arg?: A1 & A2) => Promise<Awaited<R1> & Awaited<R2>>
      : (arg?: A1 & A2) => R1 & R2
    : never
  : never;

// Additional AWS-specific feature flags
type AwsSdkCredentialsFeatures = Partial<{
  RESOLVED_CREDENTIAL_SOURCE: string;
}>;

type AwsSdkTokenFeatures = Partial<{
  RESOLVED_TOKEN_SOURCE: string;
}>;

// Deprecated credential types for backwards compatibility  
interface Credentials extends AwsCredentialIdentity {}
type CredentialProvider = Provider<Credentials>;

// Deprecated token types for backwards compatibility
interface Token extends TokenIdentity {}
type TokenProvider = Provider<Token>;

// AWS identity properties for client configuration
interface AwsIdentityProperties {
  callerClientConfig?: {
    credentials?: AwsCredentialIdentity | AwsCredentialIdentityProvider;
    credentialDefaultProvider?: (input?: any) => AwsCredentialIdentityProvider;
    logger?: Logger;
    profile?: string;
    region(): Promise<string>;
    requestHandler?: RequestHandler<any, any>;
  };
}

// Runtime configuration providers
type RuntimeConfigIdentityProvider<T> = (awsIdentityProperties?: AwsIdentityProperties) => Promise<T>;
type RuntimeConfigAwsCredentialIdentityProvider = RuntimeConfigIdentityProvider<AwsCredentialIdentity>;