I wonder if this statement stands true in all scenarios. Are there cases when you cannot modify a Response instance after its creation?

For example, you cannot modify an existing response's status or statusText. It doesn't throw but neither does it apply the change:

let r = new Response(null, { status: 301 })

r.status = 200
console.log(r.status) // 301

I'm quite sure you cannot change the response body either this way. It makes me thinking about the practicality of the augmentResponse function.

Perhaps we should illustrate a custom response generator function based on the input:

function serviceResponse(json) {
  const response = HttpResponse.json(json, {
    // Come up with some reusable defaults here. 
  })
  return response
}

What do you think about this?

@kettanaito I did not know about this, but it can be a valid point for some properties.

I guess the approach to these reusable helper functions highly depends on the use case and their goal. For example, I needed a helper that enriches any kind of response with an auth token stored in a cookie. So my preferred implementation has been to accept a response and not construct one:

function withAuthToken<R extends Response>(token: Token, response: R): R {
  response.headers.set('Set-Cookie', `${authCookieKey}=${JSON.stringify(token)}; HttpOnly;`);
  return response;
}

Other use-cases may be better covered by an implementation similar to your suggestion. Maybe the section should mainly focus on conveying the spirit of these helpers and show examples for a "response creator/factory" and "response enhancer".

We may be getting a bit ahead of ourselves with this one. The purpose of this guide is only to help people migrate existing custom response composition use cases to the new API. I think I failed to mention that these are not the new docs, so being too specific in the migration guide only hurts us.

That being said, if I were to choose I'd go with the path of the less possible error and that being to create a response in the custom utility function. Because modifying an accepted response may give people a false impression that they can modify any response property, which is not true.

You are right that there can be as many custom functions like this one as there are use cases. We can pick one, and even with that the point will be to target people who already have a custom logic like this and show them that now there's no response exports from MSW and you should create/operate with Response instances. I believe the response generator example works fine for that.

@kettanaito I tried to compile our discussion into concise changed for the example. What do you think about the new suggestion?