feat: add commandCall method to AwsStub (#241)

Author: icholy

packages/aws-sdk-client-mock/src/awsClientStub.ts

@@ -131,6 +131,33 @@ export class AwsStub<TInput extends object, TOutput extends MetadataBearer, TCon
             });
     }
 
+    /**
+     * Returns n-th call of given Command only.
+     * @param n Index of the call
+     * @param commandType Command type to match
+     * @param input Command payload to match
+     * @param strict Should the payload match strictly (default false, will match if all defined payload properties match)
+     */
+    commandCall<TCmd extends AwsCommand<any, any>,
+        TCmdInput extends TCmd extends AwsCommand<infer TIn, any> ? TIn : never,
+        TCmdOutput extends TCmd extends AwsCommand<any, infer TOut> ? TOut : never,
+    >(
+        n: number,
+        commandType: new (input: TCmdInput) => TCmd,
+        input?: Partial<TCmdInput>,
+        strict?: boolean,
+    ): SinonSpyCall<[TCmd], Promise<TCmdOutput>> {
+        const calls = this.commandCalls(commandType, input, strict);
+        if (n < 0) {
+            n += calls.length;
+        }
+        if (n >= calls.length) {
+            // @ts-expect-error this matches the behaviour of the call method.
+            return null;
+        }
+        return calls[n];
+    }
+
     /**
      * Allows specifying the behavior for any Command with given input (parameters).
      *

packages/aws-sdk-client-mock/test/mockClient.test.ts

@@ -127,6 +127,17 @@ describe('spying on the mock', () => {
         expect(snsMock.commandCalls(PublishCommand, {...publishCmd1.input}, true)).toHaveLength(1);
     });
 
+    it('finds nth call of given command type', async () => {
+        const sns = new SNSClient({});
+        await sns.send(publishCmd1);
+        await sns.send(publishCmd2);
+
+        expect(snsMock.commandCall(0, PublishCommand).args[0].input).toStrictEqual(publishCmd1.input);
+        expect(snsMock.commandCall(1, PublishCommand).args[0].input).toStrictEqual(publishCmd2.input);
+        expect(snsMock.commandCall(-1, PublishCommand).args[0].input).toStrictEqual(publishCmd2.input);
+        expect(snsMock.commandCall(2, PublishCommand)).toBeNull();
+    });
+
     it('resets calls history', async () => {
         const sns = new SNSClient({});
         await sns.send(publishCmd1);