[v4] Deprecate res.clearCookie accepting options.maxAge and options.expires

History.md

@@ -3,6 +3,8 @@ unreleased
 
   * deps: encodeurl@~2.0.0
     - Removes encoding of `\`, `|`, and `^` to align better with URL spec
+  * Deprecate passing `options.maxAge` and `options.expires` to `res.clearCookie`
+    - Will be ignored in v5, clearCookie will set a cookie with an expires in the past to instruct clients to delete the cookie
 
 4.19.2 / 2024-03-25
 ==========

lib/response.js

@@ -822,6 +822,14 @@ res.get = function(field){
  */
 
 res.clearCookie = function clearCookie(name, options) {
+  if (options) {
+    if (options.maxAge) {
+      deprecate('res.clearCookie: Passing "options.maxAge" is deprecated and should be removed. Starting with the next major release of Express, this option will be ignored, as res.clearCookie will automatically set cookies to expire immediately. Please update your code to omit this option.');
+    }
+    if (options.expires) {
+      deprecate('res.clearCookie: Passing "options.expires" is deprecated and should be removed. Starting with the next major release of Express, this option will be ignored, as res.clearCookie will automatically set cookies to expire immediately. Please update your code to omit this option.');
+    }
+  }
   var opts = merge({ expires: new Date(1), path: '/' }, options);
 
   return this.cookie(name, '', opts);

test/res.clearCookie.js

@@ -32,5 +32,37 @@ describe('res', function(){
       .expect('Set-Cookie', 'sid=; Path=/admin; Expires=Thu, 01 Jan 1970 00:00:00 GMT')
       .expect(200, done)
     })
+
+    it('should set expires when passed', function(done) {
+      var expiresAt = new Date()
+      var app = express();
+
+      app.use(function(req, res){
+        res.clearCookie('sid', { expires: expiresAt }).end();
+      });
+
+      request(app)
+      .get('/')
+      .expect('Set-Cookie', 'sid=; Path=/; Expires=' + expiresAt.toUTCString() )
+      .expect(200, done)
+    })
+
+    it('should set both maxAge and expires when passed', function(done) {
+      var maxAgeInMs = 10000
+      var expiresAt = new Date()
+      var expectedExpires = new Date(expiresAt.getTime() + maxAgeInMs)
+      var app = express();
+
+      app.use(function(req, res){
+        res.clearCookie('sid', { expires: expiresAt, maxAge: maxAgeInMs }).end();
+      });
+
+      request(app)
+      .get('/')
+      // yes, this is the behavior. When we set a max-age, we also set expires to a date 10 sec ahead of expires
+      // even if we set max-age only, we will also set an expires 10 sec in the future
+      .expect('Set-Cookie', 'sid=; Max-Age=10; Path=/; Expires=' + expectedExpires.toUTCString())
+      .expect(200, done)
+    })
   })
 })