[RFC] URL-encode path parameters for Router.url

[ide]

This is a proposal for a public API change.

The main breaking change from v8.x to v9.x was an upgrade to path-to-regex. That PR alluded to a breaking change in encoding. Namely, parameters were not URL-encoded: parameters with safe special characters (like spaces) were not percent-encoded, and parameters with special characters that mean something in a URL, such as slashes (path separators) and question marks (query string delimiter).

The motivation for this PR is to make URL-encoding be the default since typically the parameters provided to Router.url are plain, unencoded values. Should someone need an escape hatch, they could pass in { encode: null } (I think) to disable the automatic encoding.

This addition to the changelog shows the change by example:

• [Breaking] URL-encode parameters passed to Router.url with encodeURIComponent.
  • Previously, the parameters to insert in a URL were not encoded:
  • Router.url('/:x', { x: 'hello world' }) produced "/hello world"
  • Router.url('/:x', { x: 'a/test?param#' }) would throw an error
  • Now, all parameters are safely URL-encoded by default:
  • Router.url('/:x', { x: 'hello world' }) produces "/hello%20world"
  • Router.url('/:x', { x: 'a/test?param#' }) produces "/a%2Ftest%3Fparam%23"

Updated tests, docs, and the changelog.

[ide]

@titanism would you be interested in taking a look at this change? In summary, it fixes query parameter escaping for Router.url.

[titanism]

@koa/router v12.0.0 released to npm, thanks @ide

https://github.com/koajs/router/releases/tag/v12.0.0

mirrored to koa-router