Response

El objeto res representa la respuesta HTTP que una aplicación Express envía cuando recibe una petición HTTP.

En esta documentación y por convención, el objeto siempre se denomina res (y la petición HTTP es req) pero su nombre real lo determinan los parámetros de la función de callback en la que estás trabajando.

Por ejemplo:

app.get('/user/:id', (req, res) => {
  res.send(`user ${req.params.id}`);
});

Pero también podrías tener:

app.get('/user/:id', (request, response) => {
  response.send(`user ${request.params.id}`);
});

El objeto res es una versión mejorada del propio objeto response de Node y soporta todos los campos y métodos integrados.

Propiedades

res.app

Esta propiedad contiene una referencia a la instancia de la aplicación Express que está usando el middleware.

res.app es idéntico a la propiedad req.app en el objeto de petición.

app.get('/', (req, res) => {
  console.dir(res.app.get('view engine'));
  console.dir(res.app === req.app);
  // => true
  res.send('OK');
});

res.headersSent

Propiedad booleana que indica si la aplicación envió headers HTTP para la respuesta.

app.get('/', (req, res) => {
  console.log(res.headersSent); // false
  res.send('OK');
  console.log(res.headersSent); // true
});

res.locals

Usa esta propiedad para establecer variables accesibles en las plantillas renderizadas con res.render. Las variables establecidas en res.locals están disponibles dentro de un único ciclo petición-respuesta, y no se compartirán entre peticiones.

Para mantener variables locales para usar en el renderizado de plantillas entre peticiones, usa app.locals en su lugar.

Esta propiedad es útil para exponer información a nivel de petición, como el nombre de la ruta de la petición, el usuario autenticado, los ajustes del usuario, etc., a las plantillas renderizadas dentro de la aplicación.

app.use((req, res, next) => {
  // Make `user` and `authenticated` available in templates
  res.locals.user = req.user;
  res.locals.authenticated = !req.user.anonymous;
  next();
});

res.req

Esta propiedad contiene una referencia al objeto request que se relaciona con este objeto de respuesta.

app.get('/', (req, res) => {
  console.dir(res.req === req);
  // => true
  res.send('OK');
});

Métodos

res.append()

Añade el value especificado al field del header de respuesta HTTP. Si el header no está ya establecido, crea el header con el valor especificado. El parámetro value puede ser un string o un array.

res.append('Link', ['<http://localhost/>', '<http://localhost:3000/>']);
res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly');
res.append('Warning', '199 Miscellaneous warning');

res.attachment()

Establece el campo de encabezado HTTP Content-Disposition a “attachment”. Si se proporciona un filename, entonces establece el Content-Type basándose en la extensión del archivo vía res.type(), y establece el parámetro “filename=” del Content-Disposition.

res.attachment();
// Content-Disposition: attachment

res.attachment('path/to/logo.png');
// Content-Disposition: attachment; filename="logo.png"
// Content-Type: image/png

res.clearCookie()

Borra la cookie con el name especificado enviando un header Set-Cookie que establece su fecha de expiración en el pasado. Esto indica al cliente que la cookie ha expirado y ya no es válida. Para más información sobre las options disponibles, consulta res.cookie().

res.cookie('name', 'tobi', { path: '/admin' });
res.clearCookie('name', { path: '/admin' });

res.cookie()

Establece la cookie name al value. El parámetro value puede ser un string o un objeto convertido a JSON.

Por ejemplo:

res.cookie('name', 'tobi', { domain: '.example.com', path: '/admin', secure: true });
res.cookie('remember_me', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });

Puedes establecer múltiples cookies en una sola respuesta llamando a res.cookie varias veces, por ejemplo:

res
  .status(201)
  .cookie('access_token', `Bearer ${token}`, {
    expires: new Date(Date.now() + 8 * 3600000), // cookie will be removed after 8 hours
  })
  .cookie('test', 'test')
  .redirect(301, '/admin');

La opción encode te permite elegir la función usada para la codificación del valor de la cookie. No soporta funciones asíncronas.

Caso de uso de ejemplo: Necesitas establecer una cookie para todo el dominio para otro sitio en tu organización. Este otro sitio (que no está bajo tu control administrativo) no usa valores de cookie codificados con URI.

// Default encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com' });
// Result: 'some_cross_domain_cookie=http%3A%2F%2Fmysubdomain.example.com; Domain=example.com; Path=/'

// Custom encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', {
  domain: 'example.com',
  encode: String,
});
// Result: 'some_cross_domain_cookie=http://mysubdomain.example.com; Domain=example.com; Path=/;'

La opción maxAge es una opción conveniente para establecer “expires” relativo al tiempo actual en milisegundos. Lo siguiente es equivalente al segundo ejemplo de arriba.

res.cookie('remember_me', '1', { maxAge: 900000, httpOnly: true });

Puedes pasar un objeto como parámetro value; este se serializa como JSON y es parseado por el middleware bodyParser().

res.cookie('cart', { items: [1, 2, 3] });
res.cookie('cart', { items: [1, 2, 3] }, { maxAge: 900000 });

Cuando se usa el middleware cookie-parser, este método también soporta cookies firmadas. Simplemente incluye la opción signed con valor true. Entonces, res.cookie() usará el secreto pasado a cookieParser(secret) para firmar el valor.

res.cookie('name', 'tobi', { signed: true });

Luego, puedes acceder a este valor a través del objeto req.signedCookies.

res.download()

Transfiere el archivo en path como un “attachment”. Típicamente, los navegadores pedirán al usuario que lo descargue. Por defecto, el parámetro “filename=” del header Content-Disposition se deriva del argumento path, pero puede sobrescribirse con el parámetro filename. Si path es relativo, entonces se basará en el directorio de trabajo actual del proceso o la opción root, si se proporciona.

El método invoca la función de callback fn(err) cuando la transferencia se completa o cuando ocurre un error. Si se especifica la función de callback y ocurre un error, la función de callback debe manejar explícitamente el proceso de respuesta ya sea finalizando el ciclo petición-respuesta, o pasando el control a la siguiente ruta.

res.download('/report-12345.pdf');

res.download('/report-12345.pdf', 'report.pdf');

res.download('/report-12345.pdf', 'report.pdf', (err) => {
  if (err) {
    // Handle error, but keep in mind the response may be partially-sent
    // so check res.headersSent
  } else {
    // decrement a download credit, etc.
  }
});

res.end()

Finaliza el proceso de respuesta. Este método viene del núcleo de Node, específicamente del método response.end() de http.ServerResponse.

Úsalo para finalizar rápidamente la respuesta sin ningún dato. Si necesitas responder con datos, usa en su lugar métodos como res.send() y res.json().

res.end();
res.status(404).end();

res.format()

Realiza negociación de contenido en el header HTTP Accept del objeto de petición, cuando está presente. Usa req.accepts() para seleccionar un manejador para la petición, basándose en los tipos aceptables ordenados por sus valores de calidad. Si el header no se especifica, se invoca el primer callback. Cuando no se encuentra ninguna coincidencia, el servidor responde con 406 “Not Acceptable”, o invoca el callback default.

El header de respuesta Content-Type se establece cuando se selecciona un callback. Sin embargo, puedes alterar esto dentro del callback usando métodos como res.set() o res.type().

El siguiente ejemplo respondería con { "message": "hey" } cuando el campo de encabezado Accept está establecido a “application/json” o ”*/json” (sin embargo, si es ”*/*”, entonces la respuesta será “hey”).

res.format({
  'text/plain'() {
    res.send('hey');
  },

  'text/html'() {
    res.send('<p>hey</p>');
  },

  'application/json'() {
    res.send({ message: 'hey' });
  },

  default() {
    // log the request and respond with 406
    res.status(406).send('Not Acceptable');
  },
});

Además de los tipos MIME canonizados, también puedes usar nombres de extensión mapeados a estos tipos para una implementación un poco menos verbosa:

res.format({
  text() {
    res.send('hey');
  },

  html() {
    res.send('<p>hey</p>');
  },

  json() {
    res.send({ message: 'hey' });
  },
});

res.get()

Devuelve el header de respuesta HTTP especificado por field. La coincidencia es insensible a mayúsculas y minúsculas.

res.get('Content-Type');
// => "text/plain"

res.json()

Envía una respuesta JSON. Este método envía una respuesta (con el content-type correcto) que es el parámetro convertido a un string JSON usando JSON.stringify().

El parámetro puede ser cualquier tipo JSON, incluyendo objeto, array, string, Boolean, número, o null, y también puedes usarlo para convertir otros valores a JSON.

res.json(null);
res.json({ user: 'tobi' });
res.status(500).json({ error: 'message' });

res.jsonp()

Envía una respuesta JSON con soporte JSONP. Este método es idéntico a res.json(), excepto que opta por el soporte de callback JSONP.

res.jsonp(null);
// => callback(null)

res.jsonp({ user: 'tobi' });
// => callback({ "user": "tobi" })

res.status(500).jsonp({ error: 'message' });
// => callback({ "error": "message" })

Por defecto, el nombre del callback JSONP es simplemente callback. Sobrescribe esto con el

ajuste de nombre de callback jsonp.

Los siguientes son algunos ejemplos de respuestas JSONP usando el mismo código:

// ?callback=foo
res.jsonp({ user: 'tobi' });
// => foo({ "user": "tobi" })

app.set('jsonp callback name', 'cb');

// ?cb=foo
res.status(500).jsonp({ error: 'message' });
// => foo({ "error": "message" })

res.links()

Une los links proporcionados como propiedades del parámetro para rellenar el campo del header Link de la respuesta HTTP.

Por ejemplo, la siguiente llamada:

res.links({
  next: 'http://api.example.com/users?page=2',
  last: 'http://api.example.com/users?page=5',
});

Produce los siguientes resultados:

Link: <http://api.example.com/users?page=2>; rel="next",
      <http://api.example.com/users?page=5>; rel="last"

res.location()

Establece el header HTTP Location de la respuesta al parámetro path especificado.

res.location('/foo/bar');
res.location('http://example.com');

res.redirect()

Redirige a la URL derivada del path especificado, con el status especificado, un entero positivo que corresponde a un código de estado HTTP. Si no se especifica, status por defecto es 302 "Found".

res.redirect('/foo/bar');
res.redirect('http://example.com');
res.redirect(301, 'http://example.com');
res.redirect('../login');

Las redirecciones pueden ser una URL completa para redirigir a un sitio diferente:

res.redirect('https://google.com');

Las redirecciones pueden ser relativas a la raíz del nombre del host. Por ejemplo, si la aplicación está en http://example.com/admin/post/new, lo siguiente redirigiría a la URL http://example.com/admin:

res.redirect('/admin');

Las redirecciones pueden ser relativas a la URL actual. Por ejemplo, desde http://example.com/blog/admin/ (nótese la barra final), lo siguiente redirigiría a la URL http://example.com/blog/admin/post/new.

res.redirect('post/new');

Redirigir a post/new desde http://example.com/blog/admin (sin barra final), redirigirá a http://example.com/blog/post/new.

Si el comportamiento anterior te resulta confuso, piensa en los segmentos de ruta como directorios (con barras finales) y archivos, y empezará a tener sentido.

Las redirecciones relativas a la ruta también son posibles. Si estuvieras en http://example.com/admin/post/new, lo siguiente redirigiría a http://example.com/admin/post:

res.redirect('..');

Consulta también Mejores prácticas de seguridad: Prevenir vulnerabilidades de redirección abierta.

res.render()

Renderiza una view y envía el string HTML renderizado al cliente. Parámetros opcionales:

• locals, un objeto cuyas propiedades definen variables locales para la vista.
• callback, una función de callback. Si se proporciona, el método devuelve tanto el posible error como el string renderizado, pero no realiza una respuesta automatizada. Cuando ocurre un error, el método invoca next(err) internamente.

El argumento view es un string que es la ruta del archivo de la vista a renderizar. Puede ser una ruta absoluta, o una ruta relativa al ajuste views. Si la ruta no contiene una extensión de archivo, entonces el ajuste view engine determina la extensión del archivo. Si la ruta contiene una extensión de archivo, entonces Express cargará el módulo para el motor de plantillas especificado (mediante require()) y lo renderizará usando la función __express del módulo cargado.

Para más información, consulta Uso de motores de plantillas con Express.

// send the rendered view to the client
res.render('index');

// if a callback is specified, the rendered HTML string has to be sent explicitly
res.render('index', (err, html) => {
  res.send(html);
});

// pass a local variable to the view
res.render('user', { name: 'Tobi' }, (err, html) => {
  // ...
});

res.send()

Envía la respuesta HTTP.

El parámetro body puede ser un objeto Buffer, un String, un objeto, un Boolean, o un Array. Por ejemplo:

res.send(Buffer.from('whoop'));
res.send({ some: 'json' });
res.send('<p>some html</p>');
res.status(404).send('Sorry, we cannot find that!');
res.status(500).send({ error: 'something blew up' });

Este método realiza muchas tareas útiles para respuestas simples que no son de streaming: Por ejemplo, asigna automáticamente el campo de encabezado HTTP Content-Length y proporciona soporte automático para HEAD y frescura de caché HTTP.

Cuando el parámetro es un objeto Buffer, el método establece el campo del header de respuesta Content-Type a “application/octet-stream”, a menos que se haya definido previamente como se muestra abajo:

res.set('Content-Type', 'text/html');
res.send(Buffer.from('<p>some html</p>'));

Cuando el parámetro es un String, el método establece Content-Type a “text/html”:

res.send('<p>some html</p>');

Cuando el parámetro es un Array o un Object, Express responde con la representación JSON:

res.send({ user: 'tobi' });
res.send([1, 2, 3]);

res.sendFile()

Transfiere el archivo en la path dada. Establece el campo del header HTTP de respuesta Content-Type basándose en la extensión del nombre del archivo. A menos que la opción root esté establecida en el objeto de opciones, path debe ser una ruta absoluta al archivo.

El método invoca la función de callback fn(err) cuando la transferencia se completa o cuando ocurre un error. Si se especifica la función de callback y ocurre un error, la función de callback debe manejar explícitamente el proceso de respuesta ya sea finalizando el ciclo petición-respuesta, o pasando el control a la siguiente ruta.

Aquí hay un ejemplo de uso de res.sendFile con todos sus argumentos.

app.get('/file/:name', (req, res, next) => {
  const options = {
    root: path.join(__dirname, 'public'),
    dotfiles: 'deny',
    headers: {
      'x-timestamp': Date.now(),
      'x-sent': true,
    },
  };

  const fileName = req.params.name;
  res.sendFile(fileName, options, (err) => {
    if (err) {
      next(err);
    } else {
      console.log('Sent:', fileName);
    }
  });
});

El siguiente ejemplo ilustra el uso de res.sendFile para proporcionar soporte detallado para servir archivos:

app.get('/user/:uid/photos/:file', (req, res) => {
  const uid = req.params.uid;
  const file = req.params.file;

  req.user.mayViewFilesFrom(uid, (yes) => {
    if (yes) {
      res.sendFile(`/uploads/${uid}/${file}`);
    } else {
      res.status(403).send("Sorry! You can't see that.");
    }
  });
});

Para más información, o si tienes problemas o dudas, consulta send.

res.sendStatus()

Establece el código de estado HTTP de la respuesta a statusCode y envía el mensaje de estado registrado como cuerpo de respuesta de texto. Si se especifica un código de estado desconocido, el cuerpo de la respuesta será solo el número del código.

res.sendStatus(404);

Más sobre códigos de estado HTTP

res.set()

Establece el header HTTP field de la respuesta a value. Para establecer múltiples campos a la vez, pasa un objeto como parámetro.

res.set('Content-Type', 'text/plain');

res.set({
  'Content-Type': 'text/plain',
  'Content-Length': '123',
  ETag: '12345',
});

Alias de res.header(field [, value]).

res.status()

Establece el estado HTTP para la respuesta. Es un alias encadenable del response.statusCode de Node.

res.status(403).end();
res.status(400).send('Bad Request');
res.status(404).sendFile('/absolute/path/to/404.png');

res.type()

Establece el encabezado HTTP Content-Type al tipo MIME determinado por el type especificado. Si type contiene el carácter ”/”, entonces establece el Content-Type al valor exacto de type, de lo contrario se asume que es una extensión de archivo y el tipo MIME se busca usando el método contentType() del paquete mime-types.

res.type('.html'); // => 'text/html'
res.type('html'); // => 'text/html'
res.type('json'); // => 'application/json'
res.type('application/json'); // => 'application/json'
res.type('png'); // => image/png:

Alias de res.contentType(type).

res.vary()

Añade el campo al header de respuesta Vary, si no está ya presente.

res.vary('User-Agent').render('docs');