Merge `searchParams` with what is specified in input URL

[marshall007]

This is not a bug because the behavior is documented in the README:

Search parameters to include in the request URL. Setting this will override all existing search parameters in the input URL.

Nevertheless, I think this behavior is unintuitive. We are in the process of migrating a large codebase from axios -> ky and this difference is difficult to accommodate.

It would make more sense to me if the default behavior was to merge URLSearchParams specified in the input URL with anything specified in options.searchParams. It would be easy to reintroduce the current behavior with a beforeRequest hook that rewrites the request URL based on options.searchParams, if desired.

await ky.post('/example?foo=bar', {
  searchParams: {
    id: 'id'
  }
});

// Expected: -> POST /example?foo=bar&id=id
// Actual: -> POST /example?id=id

[sindresorhus]

I looked into how other HTTP libraries handle this, and the majority merge rather than override: axios, Python requests, Rust reqwest, Kotlin OkHttp, and Swift Alamofire all append params to existing URL query parameters. Ky is the outliers here.

Thinking more about this, I agree merge is the more intuitive behavior. When you write /example?foo=bar with searchParams: {id: 'id'}, the foo=bar is right there in the URL. Silently dropping it feels like data loss. And the override case is self-solving: if you want full control, just use a clean URL without params. The merge case has no clean workaround.

We can document this for anyone that actually needs to replace:

const url = new URL('/example?foo=bar', location.origin);
url.search = '';
await ky(url, {searchParams: {id: 'id'}});
//=> /example?id=id

I'm leaning towards changing this. @sholladay Thoughts?

[sholladay]

Strictly speaking, I prefer to layer merge behavior on top of a simpler, non-merge API, and make it opt-in. That makes it easier to avoid any bugs or edge cases caused by the merging algorithm, which is common in my experience.

That being said, if we're keeping the merge-by-default behavior of the rest of Ky's options, I think it only make sense to merge search params. All or nothing, IMO.

It should probably have special handling for { myParam : undefined } to delete specific, pre-existing parameters. Similar to what we do for headers.