[Feature Request] typescript type for common config properties to use with a variety of different clients

[jedwards1211]

Describe the feature

I'd like a typescript type that accepts common properties I might like to pass to services like S3ClientConfig, EC2ClientConfig, etc.

Use Case

I have a lot of libraries that accept an awsConfig to pass to a variety of different clients they construct and use. Often I'll use something like Omit<S3ClientConfig, 'extensions'> but obviously that's not perfect, and lately it's becoming less and less assignable to config types for other services.

Having to pass in a separate config for each client type to these libraries would be a waste of time. It's mostly just credentials and region I need to pass to everything, but there are a lot of other common things like maxRetries config that would be nice to control from there so I just want a utility type with everything that's broadly applicable. There are even some properties like logger that don't seem to be part of any common interface even though they're duplicated on all the client config types.

Proposed Solution

Maybe an interface with the properties in https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/migrate-client-constructors.html exported from @aws-sdk/types?

Other Information

A Google search for "aws node sdk v3 typescript type for config props common to all services" yielded an AI response that seems to be hallucinated:

In the AWS SDK for JavaScript v3, the common configuration properties across all services are defined in the ClientConfig type. This type is available via the @aws-sdk/types package or, more commonly, is an inherited type within the specific client configuration objects (e.g., S3ClientConfig, DynamoDBClientConfig).

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

SDK version used

3.973.1

Environment details (OS name and version, etc.)

N/A

[jedwards1211]

Here's what I ended up creating for myself for now:

import type { DefaultsMode, SmithyConfiguration } from '@smithy/smithy-client'
import type {
  BodyLengthCalculator,
  ChecksumConstructor,
  Decoder,
  Encoder,
  HttpAuthScheme,
  HttpHandlerOptions,
  Logger,
  Provider,
  StreamCollector,
  UrlParser,
  UserAgent,
} from '@smithy/types'
import type { HttpHandlerUserInput } from '@smithy/protocol-http'
import type { UserAgentInputConfig } from '@aws-sdk/middleware-user-agent'
import type { FlexibleChecksumsInputConfig } from '@aws-sdk/middleware-flexible-checksums'
import type { HostHeaderInputConfig } from '@aws-sdk/middleware-host-header'
import type { RetryInputConfig } from '@smithy/middleware-retry'
import type { RegionInputConfig } from '@smithy/config-resolver'
import type { AwsSdkSigV4AuthInputConfig } from '@aws-sdk/core'

export type AWSClientConfig = Partial<SmithyConfiguration<HttpHandlerOptions>> &
  UserAgentInputConfig &
  FlexibleChecksumsInputConfig &
  RetryInputConfig &
  RegionInputConfig &
  AwsSdkSigV4AuthInputConfig &
  HostHeaderInputConfig & {
    /**
     * The HTTP handler to use or its constructor options. Fetch in browser and Https in Nodejs.
     */
    requestHandler?: HttpHandlerUserInput
    /**
     * A constructor for a class implementing the {@link @smithy/types#ChecksumConstructor} interface
     * that computes the SHA-256 HMAC or checksum of a string or binary buffer.
     * @internal
     */
    sha256?: ChecksumConstructor
    /**
     * The function that will be used to convert strings into HTTP endpoints.
     * @internal
     */
    urlParser?: UrlParser
    /**
     * A function that can calculate the length of a request body.
     * @internal
     */
    bodyLengthChecker?: BodyLengthCalculator
    /**
     * A function that converts a stream into an array of bytes.
     * @internal
     */
    streamCollector?: StreamCollector
    /**
     * The function that will be used to convert a base64-encoded string to a byte array.
     * @internal
     */
    base64Decoder?: Decoder
    /**
     * The function that will be used to convert binary data to a base64-encoded string.
     * @internal
     */
    base64Encoder?: Encoder
    /**
     * The function that will be used to convert a UTF8-encoded string to a byte array.
     * @internal
     */
    utf8Decoder?: Decoder
    /**
     * The function that will be used to convert binary data to a UTF-8 encoded string.
     * @internal
     */
    utf8Encoder?: Encoder
    /**
     * Disable dynamically changing the endpoint of the client based on the hostPrefix
     * trait of an operation.
     */
    disableHostPrefix?: boolean
    /**
     * Unique service identifier.
     * @internal
     */
    serviceId?: string
    /**
     * Enables IPv6/IPv4 dualstack endpoint.
     */
    useDualstackEndpoint?: boolean | Provider<boolean>
    /**
     * Enables FIPS compatible endpoints.
     */
    useFipsEndpoint?: boolean | Provider<boolean>
    /**
     * Setting a client profile is similar to setting a value for the
     * AWS_PROFILE environment variable. Setting a profile on a client
     * in code only affects the single client instance, unlike AWS_PROFILE.
     *
     * When set, and only for environments where an AWS configuration
     * file exists, fields configurable by this file will be retrieved
     * from the specified profile within that file.
     * Conflicting code configuration and environment variables will
     * still have higher priority.
     *
     * For client credential resolution that involves checking the AWS
     * configuration file, the client's profile (this value) will be
     * used unless a different profile is set in the credential
     * provider options.
     *
     */
    profile?: string
    /**
     * The provider populating default tracking information to be sent with `user-agent`, `x-amz-user-agent` header
     * @internal
     */
    defaultUserAgentProvider?: Provider<UserAgent>
    // /**
    //  * Default credentials provider; Not available in browser runtime.
    //  * @deprecated
    //  * @internal
    //  */
    // credentialDefaultProvider?: (input: any) => AwsCredentialIdentityProvider
    /**
     * Value for how many times a request will be made at most in case of retry.
     */
    maxAttempts?: number | Provider<number>
    /**
     * Specifies which retry algorithm to use.
     * @see https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-smithy-util-retry/Enum/RETRY_MODES/
     *
     */
    retryMode?: string | Provider<string>
    /**
     * Optional logger for logging debug/info/warn/error.
     */
    logger?: Logger
    // /**
    //  * Optional extensions
    //  */
    // extensions?: RuntimeExtension[]
    /**
     * The {@link @smithy/smithy-client#DefaultsMode} that will be used to determine how certain default configuration options are resolved in the SDK.
     */
    defaultsMode?: DefaultsMode | Provider<DefaultsMode>
    /**
     * A comma-separated list of case-sensitive auth scheme names.
     * An auth scheme name is a fully qualified auth scheme ID with the namespace prefix trimmed.
     * For example, the auth scheme with ID aws.auth#sigv4 is named sigv4.
     * @public
     */
    authSchemePreference?: string[] | Provider<string[]>
    /**
     * Configuration of HttpAuthSchemes for a client which provides default identity providers and signers per auth scheme.
     * @internal
     */
    httpAuthSchemes?: HttpAuthScheme[]
  }

[kuhe]

A type definition shared among clients should be derived from the public API input config types of those clients and not defined in an authoritative way elsewhere.

import type { S3ClientConfig } from "@aws-sdk/client-s3";
import type { DynamoDBClientConfig } from "@aws-sdk/client-dynamodb";

// definition of the type transform can be done by LLM, or I can provide one later.
type SharedConfig = MergeCompatibleFields<S3ClientConfig, DynamoDBClientConfig, ...>

Nearly all the interfaces you have imported in the example are from internal APIs and should not be used.

[jedwards1211]

I want the common denominator that's compatible with all AWS clients, not just merging certain ones I pick using type magic that really shouldn't be necessary. This used to be simple to do in v2, now it's a mess. Y'all are committed to having a consistent way of passing properties like credentials to any clients that use them, right? If there's a consistent pattern there should be a type for it in the public API. Maybe there's some weird client that doesn't use any credentials at all, but I sure nope no clients would require different credentials types... The same hopefully goes for at least profile, region, retry settings, logger among clients that use them?

For instance if I start using additional clients in my libraries, I don't want to have to go modify my shared config type to add those new clients. I want to declare the type once and have it work regardless of what clients I use in the future.

I already made my own package using my example above and it's more satisfactory to me than what you're proposing. But it would be a lot better if your public API would give us a type for the common properties all clients are guaranteed to support.

[kuhe]

You have a composed type which includes fields that are only supported in some subset of services. For example, FlexibleChecksumsInputConfig is S3-specific in the current set of offered services. Sigv4, credentials, FIPS, dualstack, and region, while very common, also have exception-case clients where they do not apply.

This is fine because you understand within your application that not all fields always apply.

Vending such a shared interface from the SDK implies a different level of support, even if we disclaim it. We already have some auto-generated config fields that are meaningless in some services. We cannot imply anything about hypothetical unreleased services and therefore do not plan to vend such an interface.

---

Often I'll use something like Omit<S3ClientConfig, 'extensions'> but obviously that's not perfect, and lately it's becoming less and less assignable to config types for other services.

What does it mean for this to become less assignable? I would expect S3's config type to continue to be a compatible superset for the majority of other services.

[jedwards1211]

type MustSatisfy<A, B extends A> = B

type T = MustSatisfy<EC2ClientConfig, S3ClientConfig>
// Error: Type 'S3ClientConfig' does not satisfy the constraint 'EC2ClientConfig'.
//   Type 'S3ClientConfigType' is not assignable to type 'ClientDefaults'.
//     Types of property 'extensions' are incompatible.

type T = MustSatisfy<EC2ClientConfig, Omit<S3ClientConfig, 'extensions'>>
// Error: Type 'Omit<S3ClientConfig, "extensions">' does not satisfy the constraint 'EC2ClientConfig'.
//   Type 'Omit<S3ClientConfig, "extensions">' is not assignable to type //'HttpAuthSchemeInputConfig'.
//     Types of property 'httpAuthSchemeProvider' are incompatible.
//       Type 'S3HttpAuthSchemeProvider | undefined' is not assignable to type 'EC2HttpAuthSchemeProvider | undefined'.

type T = MustSatisfy<EC2ClientConfig, Omit<S3ClientConfig, 'extensions' | 'httpAuthSchemeProvider'>>
// this finally works

I don't remember having to exclude 'httpAuthSchemeProvider' in the past, and I don't remember if I had to exclude 'extensions' either when SDK v3 was first released.

Sigv4, credentials, FIPS, dualstack, and region, while very common, also have exception-case clients where they do not apply.

Okay but among clients that use credentials for example, you're committed to using the same type, I hope? It sounds like a nightmare to me if different clients required different credentials types... it would be less of a pitfall to use a different property name if that's the case since it's such a common property. So I don't see why it would be a problem to vend a common config interface that includes an optional credentials property.

[jedwards1211]

Obviously I'm being overzealous about trying to include every possible common property whether I'll ever need it or not, but I also wish the types provided by SDK v3 made it easy to tell if there would be some weird gotcha if I pass the same common properties like credentials and region to any possible AWS client. In other words, I'm requesting that you provide that level of support, instead of just disclaiming any guarantees that clients will have a similar API.
It seems like it would take a lot of work for me to thoroughly answer that question for myself...