Why is everything possibly undefined? (& other typing/doc questions)

[mipearson]

I've been trying to work out how some of these things are intended to be used and having trouble.

Why are all fields possibly undefined?

eg (doc comments removed:

export interface Container {
    reason?: string;
    name?: string;
    exitCode?: number;
    // ...

Is the expectation that we should be putting in guard clauses for every API response, including ones that don't return an error, for things that the APIs are expected to return?

How do we use .config.* properties?

Some code naively ported from V2:

  const ecs = new ECS({});
  const clusters = await ecs.listClusters({});

  if (!clusters.clusterArns) {
    throw new CLIError(
      `Could not find any ECS clusters in ${ecs.config.region}`
    );
  }

ecs.config.region above is typed as Provider<string> | (string & Provider<string>) (which rightfully produces a warning with eslint about embedding it in a template string). Looking at Provider, it looks like it's a promise wrapper. Are we supposed to check via typeof to see if it's a function or a string, and await it if it's a function?

Where are the SDK docs?

I've been relying on intellisense & manually reading the type definitions, but it'd be nice if AWS hosted a typedoc of the various packages.

[rraziel]

One thing I would add to this, the same is true for command inputs, random example:

export interface BatchDetectDominantLanguageRequest {
    /**
     * <p>A list containing the text of the input documents. The list can contain a maximum of 25
     *       documents. Each document should contain at least 20 characters and must contain fewer than
     *       5,000 bytes of UTF-8 encoded characters.</p>
     */
    TextList: string[] | undefined;
}

While the documentation for the API clearly marks that TextList as being required.

[AllanZhengYP]

Hi @mipearson

Regarding the API reference, we just published the v3 API reference here: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index.html

We are still working on to polishing it, please feel free to open issues if you have any questions or feedbacks.

[rraziel]

Taking a closer look, and with CreateFunctionRequest as an example:

// Note: not from the code
type CreateFunctionRequest = {
    Handler?: string;
    Code: FunctionCode | undefined;
};

In practice, Handler is mandatory and Code is optional.

Would it be possible to generate code that reflects it?

type CreateFunctionRequest = {
    Handler: string;
    Code?: FunctionCode;
};

[rraziel]

Which seems to come from here: https://github.com/awslabs/smithy-typescript/blob/master/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/StructuredMemberWriter.java#L64

String optionalSuffix = shape.isUnionShape() || !isRequiredMember(member) ? "?" : "";
String typeSuffix = isRequiredMember(member) ? " | undefined" : "";

It's really not convenient the way it works right now, e.g.:

// given this (where Handler is @required and Code is optional)
type CreateFunctionRequest = {
  Handler?: string;
  Code: FunctionCode | undefined;
};
// you can do this:
const test: CreateFunctionRequest = {
  Code: undefined
};

And even if you pass Handler, you cannot omit Code and have to explicitly set it to undefined.

[andcea]

I've come across this issue as well while using the textract client.

For example:

export interface BoundingBox {
    Width?: number;
    Height?: number;
    Left?: number;
    Top?: number;
}

That object cannot logically exist without all those fields defined.

If you're using typescript this causes code that is much more unnecessarily verbose, having to check all the members for undefined.

[mipearson]

Yeah, I end up abusing ! a fair bit when working with AWS SDK responses - or co-ercing what it returns into safer types.

[rraziel]

This is what my sources are littered with:

// FIXME: https://github.com/aws/aws-sdk-js-v3/issues/1613
type BatchDetectDominantLanguageCommandInputFixed = BatchDetectDominantLanguageCommandInput & {
  TextList: NonNullable<BatchDetectDominantLanguageCommandInput['TextList']>;
}

(which could be turned into a = FixedAwsType<BatchDetectDominantLanguageCommandInput, 'TextList'> but that would mean accepting it'll never be fixed 😄 )

[allan2]

I just wanted to mention that HostedZone has string | undefined type for the field id. There are other fields affected.

The Go API Reference states that that fields are required. Perhaps parsing that reference could eliminate undefined unions.

Is there any motivation for keeping the undefined union in fields that are SDK required?

[Woodz]

This is the same issue as aws/aws-sdk-js#1553 which was not addressed in v2 JS SDK. It looks like AWS don't clearly document which fields are mandatory, particularly on output models, so the SDK just presents all fields as optional. This introduces a lot of risk of potential bugs (should we be expected to check that each field in the output model is defined?) and significantly hurts developers working in TS. To see such a major bug unresolved for almost 5 years is concerning

[G-Rath]

I've raised this issue myself before, and was told:

Using | undefined is a thought out decision explained in #1124 (comment)

[Woodz]

Ridiculous! Making all output fields optional so that they can remove them in future versions without breaking the API is just wrong. If the field is important, I will need to change my code when you stop sending the field - this is a breaking change in my app. By making important output fields optional you are actually making things worse because my code will still compile when you stop populating it!

I'm going to have to use a non-null assertion every time I use an AWS output field and my downstream code will just break if/when they stop sending it. I have no other choice (the only other option I have is to check whether an important field is null and it is, all I can do is throw an error).

[rraziel]

So, coming back to this topic, I understand there is a rationale behind the current behavior (and changing it would be a breaking change).

How about having a flag that can be passed when doing a cdktf get (or cdktf.json or an environment var) so that it generates the TS with this other model people are asking for?