[v4] Deprecate res.clearCookie accepting options.maxAge and options.expires (#5672)

* add deprecation notice for res.clearCookie maxAge/expires

* update History.md for clearCookie deprecation change

* add tests to codify deprecated behavior

Co-authored-by: Chris de Almeida <ctcpip@users.noreply.github.com>

---------

Co-authored-by: Chris de Almeida <ctcpip@users.noreply.github.com>

Author: jonchurch

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. In v5.0.0 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. In v5.0.0 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)
+    })
   })
 })