feat: allow commands to be constructed without arg if all arg fields optional (#1206)

Author: kuhe

.changeset/six-doors-speak.md

@@ -0,0 +1,6 @@
+---
+"@smithy/smithy-client": patch
+"@smithy/types": patch
+---
+
+allow command constructor argument to be omitted if no required members

packages/smithy-client/src/command.spec.ts

@@ -1,6 +1,25 @@
 import { Command } from "./command";
 
 describe(Command.name, () => {
+  it("has optional argument if the input type has no required members", async () => {
+    type OptionalInput = {
+      key?: string;
+      optional?: string;
+    };
+
+    type RequiredInput = {
+      key: string | undefined;
+      optional?: string;
+    };
+
+    class WithRequiredInputCommand extends Command.classBuilder<RequiredInput, any, any, any, any>().build() {}
+
+    class WithOptionalInputCommand extends Command.classBuilder<OptionalInput, any, any, any, any>().build() {}
+
+    new WithRequiredInputCommand({ key: "1" });
+
+    new WithOptionalInputCommand(); // expect no type error.
+  });
   it("implements a classBuilder", async () => {
     class MyCommand extends Command.classBuilder<any, any, any, any, any>()
       .ep({

packages/smithy-client/src/command.ts

@@ -11,6 +11,7 @@ import type {
   Logger,
   MetadataBearer,
   MiddlewareStack as IMiddlewareStack,
+  OptionalParameter,
   Pluggable,
   RequestHandler,
   SerdeContext,
@@ -218,13 +219,16 @@ class ClassBuilder<
    */
   public build(): {
     new (input: I): CommandImpl<I, O, C, SI, SO>;
+    new (...[input]: OptionalParameter<I>): CommandImpl<I, O, C, SI, SO>;
     getEndpointParameterInstructions(): EndpointParameterInstructions;
   } {
     // eslint-disable-next-line @typescript-eslint/no-this-alias
     const closure = this;
     let CommandRef: any;
 
     return (CommandRef = class extends Command<I, O, C, SI, SO> {
+      public readonly input: I;
+
       /**
        * @public
        */
@@ -235,8 +239,9 @@ class ClassBuilder<
       /**
        * @public
        */
-      public constructor(readonly input: I) {
+      public constructor(...[input]: OptionalParameter<I>) {
         super();
+        this.input = input ?? (({} as unknown) as I);
         closure._init(this);
       }
 

packages/types/src/client.ts

@@ -1,15 +1,15 @@
 import { Command } from "./command";
 import { MiddlewareStack } from "./middleware";
 import { MetadataBearer } from "./response";
-import { Exact } from "./util";
+import { OptionalParameter } from "./util";
 
 /**
  * @public
  *
  * A type which checks if the client configuration is optional.
  * If all entries of the client configuration are optional, it allows client creation without passing any config.
  */
-export type CheckOptionalClientConfig<T> = Exact<Partial<T>, T> extends true ? [] | [T] : [T];
+export type CheckOptionalClientConfig<T> = OptionalParameter<T>;
 
 /**
  * @public

packages/types/src/util.spec.ts

@@ -0,0 +1,40 @@
+import type { Exact, OptionalParameter } from "./util";
+
+type Assignable<LHS, RHS> = [RHS] extends [LHS] ? true : false;
+
+type OptionalInput = {
+  key?: string;
+  optional?: string;
+};
+
+type RequiredInput = {
+  key: string | undefined;
+  optional?: string;
+};
+
+{
+  // optional parameter transform of an optional input is not equivalent to exactly 1 parameter.
+  type A = [...OptionalParameter<OptionalInput>];
+  type B = [OptionalInput];
+  type C = [OptionalInput] | [];
+
+  const assert1: Exact<A, B> = false as const;
+  const assert2: Exact<A, C> = true as const;
+
+  const assert3: Assignable<A, []> = true as const;
+  const assert4: A = [];
+
+  const assert5: Assignable<A, [{ key: "" }]> = true as const;
+  const assert6: A = [{ key: "" }];
+}
+
+{
+  // optional parameter transform of a required input is equivalent to exactly 1 parameter.
+  type A = [...OptionalParameter<RequiredInput>];
+  type B = [RequiredInput];
+
+  const assert1: Exact<A, B> = true as const;
+  const assert2: Assignable<A, []> = false as const;
+  const assert3: Assignable<A, [{ key: "" }]> = true as const;
+  const assert4: A = [{ key: "" }];
+}

packages/types/src/util.ts

@@ -181,3 +181,11 @@ export interface RetryStrategy {
     args: FinalizeHandlerArguments<Input>
   ) => Promise<FinalizeHandlerOutput<Output>>;
 }
+
+/**
+ * @public
+ *
+ * Indicates the parameter may be omitted if the parameter object T
+ * is equivalent to a Partial<T>, i.e. all properties optional.
+ */
+export type OptionalParameter<T> = Exact<Partial<T>, T> extends true ? [] | [T] : [T];

smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/ServiceAggregatedClientGenerator.java

@@ -22,6 +22,7 @@
 import software.amazon.smithy.codegen.core.SymbolProvider;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.model.knowledge.TopDownIndex;
+import software.amazon.smithy.model.shapes.MemberShape;
 import software.amazon.smithy.model.shapes.OperationShape;
 import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.utils.SmithyInternalApi;
@@ -94,19 +95,28 @@ public void run() {
                 writer.writeDocs(
                     "@see {@link " + operationSymbol.getName() + "}"
                 );
-                writer.write("$L(\n"
-                            + "  args: $T,\n"
-                            + "  options?: $T,\n"
-                            + "): Promise<$T>;", methodName, input, applicationProtocol.getOptionsType(), output);
-                writer.write("$L(\n"
-                             + "  args: $T,\n"
-                             + "  cb: (err: any, data?: $T) => void\n"
-                             + "): void;", methodName, input, output);
-                writer.write("$L(\n"
-                            + "  args: $T,\n"
-                            + "  options: $T,\n"
-                            + "  cb: (err: any, data?: $T) => void\n"
-                            + "): void;", methodName, input, applicationProtocol.getOptionsType(), output);
+                boolean inputOptional = model.getShape(operation.getInputShape()).map(
+                    shape -> shape.getAllMembers().values().stream().noneMatch(MemberShape::isRequired)
+                ).orElse(true);
+                if (inputOptional) {
+                    writer.write("$L(): Promise<$T>;", methodName, output);
+                }
+                writer.write("""
+                    $1L(
+                      args: $2T,
+                      options?: $3T,
+                    ): Promise<$4T>;
+                    $1L(
+                      args: $2T,
+                      cb: (err: any, data?: $4T) => void
+                    ): void;
+                    $1L(
+                      args: $2T,
+                      options: $3T,
+                      cb: (err: any, data?: $4T) => void
+                    ): void;""",
+                    methodName, input, applicationProtocol.getOptionsType(), output
+                );
                 writer.write("");
             }
         });