Review and Update v5.x Documentation against v4.x

[UlisesGascon]

In our recent TC meeting, we discussed the necessity to review the v5.x documentation due to discrepancies with changes made in v4.x that were not ported over.

Additionally, we need to implement a GitHub Action that will automatically add a comment to any PR that modifies files within the ../v4/.. folder, reminding contributors to review if these changes also affect v5.x. (see: #1514 )

[crandmck]

Thanks for captuing this @UlisesGascon

[UlisesGascon]

I will start to work on this

[UlisesGascon]

I just invested some time to check what is missing potentially in the migration guide and the 5.x API based on the changelog

Legend

• 🍿 it is ignored as it is not relevant to Express 5 Docs or migration
• ✅ it was confirmed that is present in Docs and/or Migration
• 🚩 it will require some work potentially

Changelog digestion

5.0.0-beta.3 / 2024-03-25

This incorporates all changes after 4.19.1 up to 4.19.2. 🍿 (Ignored)

5.0.0-beta.2 / 2024-03-20

This incorporates all changes after 4.17.2 up to 4.19.1. 🍿 (Ignored)

5.0.0-beta.1 / 2022-02-14

This is the first Express 5.0 beta release, based off 4.17.2 and includes
changes from 5.0.0-alpha.8.

• change:
  • Default "query parser" setting to 'simple' 🚩 (Requires reference in the Migration Guide?)
  • Requires Node.js 4+ ✅ (Was included)
  • Use mime-types for file to content type mapping 🍿 (Ignored)
• deps: array-flatten@3.0.0 🍿 (Ignored)
• deps: body-parser@2.0.0-beta.1
  • req.body is no longer always initialized to {} 🚩 (Requires reference in the Migration Guide?)
  • urlencoded parser now defaults extended to false 🚩 (Requires reference in the Migration Guide?)
  • Use on-finished to determine when body read 🍿 (Ignored)
• deps: router@2.0.0-beta.1
  • Add new ?, *, and + parameter modifiers ✅ (Was included)
  • Internalize private router.process_params method 🚩 (Requires reference in the Migration Guide?)
  • Matching group expressions are only RegExp syntax ✅ (Was included)
  • Named matching groups no longer available by position in req.params ✅ (Was included)
  • Regular expressions can only be used in a matching group ✅ (Was included)
  • Remove debug dependency 🍿 (Ignored)
  • Special * path segment behavior removed 🚩 (Requires reference in the Migration Guide?)
  • deps: array-flatten@3.0.0 🍿 (Ignored)
  • deps: parseurl@~1.3.3 🍿 (Ignored)
  • deps: path-to-regexp@3.2.0 🍿 (Ignored)
  • deps: setprototypeof@1.2.0 🍿 (Ignored)
• deps: send@1.0.0-beta.1 🍿 (Ignored)
  • Change dotfiles option default to 'ignore'
  • Remove hidden option; use dotfiles option instead
  • Use mime-types for file to content type mapping
  • deps: debug@3.1.0
• deps: serve-static@2.0.0-beta.1 🍿 (Ignored)
  • Change dotfiles option default to 'ignore'
  • Remove hidden option; use dotfiles option instead
  • Use mime-types for file to content type mapping
  • deps: send@1.0.0-beta.1

5.0.0-alpha.8 / 2020-03-25

This is the eighth Express 5.0 alpha release, based off 4.17.1 and includes
changes from 5.0.0-alpha.7. 🍿 (Ignored)

5.0.0-alpha.7 / 2018-10-26

This is the seventh Express 5.0 alpha release, based off 4.16.4 and includes
changes from 5.0.0-alpha.6.

The major change with this alpha is the basic support for returned, rejected
Promises in the router.

• remove: 🍿 (Ignored)
  • path-to-regexp dependency
• deps: debug@3.1.0 🍿 (Ignored)
  • Add DEBUG_HIDE_DATE environment variable
  • Change timer to per-namespace instead of global
  • Change non-TTY date format
  • Remove DEBUG_FD environment variable support
  • Support 256 namespace colors
• deps: router@2.0.0-alpha.1
  • Add basic support for returned, rejected Promises 🚩 (Requires reference in the Migration Guide?)
  • Fix JSDoc for Router constructor 🍿 (Ignored)
  • deps: debug@3.1.0 🍿 (Ignored)
  • deps: parseurl@~1.3.2 🍿 (Ignored)
  • deps: setprototypeof@1.1.0 🍿 (Ignored)
  • deps: utils-merge@1.0.1 🍿 (Ignored)

5.0.0-alpha.6 / 2017-09-24

This is the sixth Express 5.0 alpha release, based off 4.15.5 and includes
changes from 5.0.0-alpha.5.

• remove:
  • res.redirect(url, status) signature - use res.redirect(status, url) 🚩 (Requires reference in the Migration Guide?)
  • res.send(status, body) signature - use res.status(status).send(body) ✅ (Was included)
• deps: router@~1.3.1 🍿 (Ignored)
  • deps: debug@2.6.8

5.0.0-alpha.5 / 2017-03-06

This is the fifth Express 5.0 alpha release, based off 4.15.2 and includes
changes from 5.0.0-alpha.4. 🍿 (Ignored)

5.0.0-alpha.4 / 2017-03-01

This is the fourth Express 5.0 alpha release, based off 4.15.0 and includes
changes from 5.0.0-alpha.3.

• remove:
  • Remove Express 3.x middleware error stubs 🚩 (Requires reference in the Migration Guide?)
• deps: router@~1.3.0 🍿 (Ignored)
  • Add next("router") to exit from router
  • Fix case where router.use skipped requests routes did not
  • Skip routing when req.url is not set
  • Use %o in path debug to tell types apart
  • deps: debug@2.6.1
  • deps: setprototypeof@1.0.3
  • perf: add fast match path for * route

5.0.0-alpha.3 / 2017-01-28

This is the third Express 5.0 alpha release, based off 4.14.1 and includes
changes from 5.0.0-alpha.2.

• remove:
  • res.json(status, obj) signature - use res.status(status).json(obj) ✅ (Was included)
  • res.jsonp(status, obj) signature - use res.status(status).jsonp(obj) ✅ (Was included)
  • res.vary() (no arguments) -- provide a field name as an argument 🚩 (Missing in both?)
• deps: array-flatten@2.1.1 🍿 (Ignored)
• deps: path-is-absolute@1.0.1 🍿 (Ignored)
• deps: router@~1.1.5 🍿 (Ignored)
  • deps: array-flatten@2.0.1 🍿 (Ignored)
  • deps: methods@~1.1.2 🍿 (Ignored)
  • deps: parseurl@~1.3.1 🍿 (Ignored)
  • deps: setprototypeof@1.0.2 🍿 (Ignored)

5.0.0-alpha.2 / 2015-07-06

This is the second Express 5.0 alpha release, based off 4.13.1 and includes
changes from 5.0.0-alpha.1.

• remove:
  • app.param(fn) 🚩 (Present in Docs!)
  • req.param() -- use req.params, req.body, or req.query instead ✅ (Was included)
• change:
  • res.render callback is always async, even for sync view engines 🚩 (Docs inacurate?)
  • The leading : character in name for app.param(name, fn) is no longer removed ✅ (Was included)
  • Use router module for routing 🚩 (Requires research)
  • Use path-is-absolute module for absolute path detection 🚩 (Requires research)

5.0.0-alpha.1 / 2014-11-06

This is the first Express 5.0 alpha release, based off 4.10.1.

• remove:
  • app.del - use app.delete ✅ (Was included)
  • req.acceptsCharset - use req.acceptsCharsets ✅ (Was included)
  • req.acceptsEncoding - use req.acceptsEncodings ✅ (Was included)
  • req.acceptsLanguage - use req.acceptsLanguages ✅ (Was included)
  • res.json(obj, status) signature - use res.json(status, obj) ✅ (Was included)
  • res.jsonp(obj, status) signature - use res.jsonp(status, obj) ✅ (Was included)
  • res.send(body, status) signature - use res.send(status, body) ✅ (Was included)
  • res.send(status) signature - use res.sendStatus(status) ✅ (Was included)
  • res.sendfile - use res.sendFile instead ✅ (Was included)
  • express.query middleware 🚩 (Missing in both?)
• change:
  • req.host now returns host (hostname:port) - use req.hostname for only hostname ✅ (Was included)
  • req.query is now a getter instead of a plain property 🚩 (Check in guide, ok in migration)
• add:
  • app.router is a reference to the base router ✅ (Was included)

[krzysdz]

The documentation and migration guide are also missing some changes from 5.0.0 and e.g. suggest using '(.*)' in paths, while now it should be /(.*)/ (see expressjs/express#5936 (comment)).

[blakeembrey]

Thanks @krzysdz, anywhere it would have been * can probably just be *foo, so "*all" is also fine. TL;DR for routing changes of Express 4 -> 5 should be:

1. * requires a name, e.g. *name.
2. The ? is replaced with {} to make anything optional, e.g. /:foo? becomes {/:foo}.
3. Regular expression characters are not supported, you cannot use [] or () in the regex but you can use it literally by escaping, e.g. \\[.

Also documented here: https://github.com/pillarjs/path-to-regexp?tab=readme-ov-file#express--4x.

[bjohansebas]

expressjs/express#6191 This should also be included in the migration, i'm just noting it here as a reminder.

[bjohansebas]

I’d say we have the documentation up to date regarding APIs and migration guides, so I’m going to close the issue