Difference between response.status and response.writeHead?

response.status(...) assigns a status code that will be used in the future. The headers are not sent until the response body is sent.

response.writeHead(...) actually queues the response headers to be sent out immediately. That means you can no-longer assign any headers or status codes for that response afterward since all of those have already been sent out.

Typically you'd use the former pattern, but .writeHead is useful if you want to get time-to-first-byte (TTFB) happening sooner.

From the statusCode point of view, all of these are identical:

1. Calling res.status(statusCode)
2. Setting the res.statusCode property directly
3. Passing a statusCode to res.writeHead(statusCode, ...)
4. Calling res.sendStatus(statusCode)

For the statusCode itself, they all do the same thing which is to set the .statusCode property. That property value is then used whenever the response sends headers (which might be immediately or might be later depending upon which option you chose). You can see this by looking at the Express and http source code (references below).

Calling res.status() and setting res.statusCode just set the property for later use.

Calling res.writeHead() sets the res.statusCode property and will then cause the headers to be flushed immediately, rather than their normal behavior of being queued to be sent later. But, from the statusCode point of view, there is no difference.

Calling res.sendStatus() set the res.statusCode property and will then cause the response to be sent immediately with just headers, no body. This is often used for responses that need no body (redirects, error codes, etc...).

---

For questions like this, you can just go look at the source code. For .status(), we see this:

res.status = function status(code) {
  this.statusCode = code;
  return this;
};

Then, in the nodejs code for an http.ServerResponse, you can see that calling .writeHead() yourself, just ends up setting the same this.statusCode property before it calls .end() to flush out the headers and the rest of the response:

And, if you then look at the doc for http.ServerResponse, you see this:

response.statusCode

Added in: v0.4.0

Default: 200

When using implicit headers (not calling response.writeHead() explicitly), this property controls the status code that will be sent to the client when the headers get flushed.

So, .status() is just a method for setting the statusCode property which is what the response value will be sent to when the headers are eventually sent (in the future) and (from the statusCode point of view) is exactly the same as calling writeHead() and passing it the status.

Express is trying to play at a little bit higher level of abstraction so they created a method for setting the statusCode separately which can be called at any time before the response is set.