URLSearchParams API should accept numbers for values

[artyil]

Actual implementation of URLSearchParams.constructor and URLSearchParams.prototype.set methods in the browsers will accept any value as value, including number or Integer.

TLDR:
new URLSearchParams([['foo', 1]]) and new URLSearchParams().set('bar', 1) should compile without TS errors

It works in current implementation, because numeric value will be coerced to actual USVString value, which is a string.

Unfortunately, current TS definition of type URLSearchParams in lid.dom.d.ts will only allow strings for above mentioned setters. Below are the definitions.

I can understand that the definitions are mirroring the W3C specifications but I do believe it is not the expected experience for developers.

The actual definition enforces developers to make unnecessary operations (helpers / utils / map-reduces) to overcome TS errors 👋

Can we reconsider to allow values to be numeric to mentioned setters? This won't break any current bahavior or actual implementation.

Even as per MDN examples constructor and URLSearchParams.prototype.set it should work as expected:

// Pass in a sequence
var params3 = new URLSearchParams([["foo", 1],["bar", 2]]);

//Add a third parameter.
params.set('baz', 3);

Which works in browser but doesn't work in TS.

TypeScript Version: 3.4.3
output with tsc typescript@next

a.ts:3:34 - error TS2345: Argument of type '{ foo: number; bar: string; }' is not assignable to parameter of type 'string | Record<string, string> | URLSearchParams | string[][]'.
  Type '{ foo: number; bar: string; }' is not assignable to type 'string'.

3 const url2 = new URLSearchParams({ foo: 1, bar: '1' }) // <- FAILS
                                   ~~~~~~~~~~~~~~~~~~~~

a.ts:5:34 - error TS2345: Argument of type '(string | number)[][]' is not assignable to parameter of type 'string | Record<string, string> | URLSearchParams | string[][]'.
  Type '(string | number)[][]' is not assignable to type 'string[][]'.
    Type '(string | number)[]' is not assignable to type 'string[]'.
      Type 'string | number' is not assignable to type 'string'.
        Type 'number' is not assignable to type 'string'.

5 const url3 = new URLSearchParams([['foo', 1], ['bar', '1']]) // <- FAILS
                                   ~~~~~~~~~~~~~~~~~~~~~~~~~~

a.ts:8:17 - error TS2345: Argument of type '1' is not assignable to parameter of type 'string'.

8 url4.set('foo', 1); // <- FAILS
                  ~


Found 3 errors.

Search Terms:
Typescript URLSearchParams invalid constructor
Typescript URLSearchParams won't accept numbers as value
Typescript URLSearchParams won't accept numeric values
standard lib.dom.d.ts URLSearchParams allow numbers as values
Typescript URLSearchParams coercion number to string

Code

const url = new URLSearchParams({foo: 'bar'}) // <- OK 

const url2 = new URLSearchParams({ foo: 1, bar: '1' }) // <- FAILS

const url3 = new URLSearchParams([['foo', 1], ['bar', '1']]) // <- FAILS

const url4 = new URLSearchParams([['bar', '2']]) // <- OK
url4.set('foo', 1); // <- FAILS

Expected behavior:
All above cases should work, because numeric values are being coerced to strings

Actual behavior:
TS won't compile due to URLSearchParams definitions only accept string for value

interface URLSearchParams {
    /**
     * Appends a specified key/value pair as a new search parameter.
     */
    append(name: string, value: string): void;
    /**
     * Deletes the given search parameter, and its associated value, from the list of all search parameters.
     */
    delete(name: string): void;
    /**
     * Returns the first value associated to the given search parameter.
     */
    get(name: string): string | null;
    /**
     * Returns all the values association with a given search parameter.
     */
    getAll(name: string): string[];
    /**
     * Returns a Boolean indicating if such a search parameter exists.
     */
    has(name: string): boolean;
    /**
     * Sets the value associated to a given search parameter to the given value. If there were several values, delete the others.
     */
    set(name: string, value: string): void;
    sort(): void;
    forEach(callbackfn: (value: string, key: string, parent: URLSearchParams) => void, thisArg?: any): void;
}

declare var URLSearchParams: {
    prototype: URLSearchParams;
    new(init?: string[][] | Record<string, string> | string | URLSearchParams): URLSearchParams;
};

Playground Link:
link

Related Issues:
microsoft/TypeScript#15338

[nmain]

I personally would prefer not to see this change. The automatic coercion of non-strings to strings that exists in many DOM apis is very implicit and I like that typescript is more strict about it, instead forcing me to explicitly Number() or .toString() a numeric that is going to be used as a string.

[CaptainOfPhB]

I think use .toString() is better, no need to change TypeScript.

[artyil]

@nmain @CaptainInPHW I truly believe that it doesn't make any sense to justify anything in this thread with a personal preference(s). If you would like to open a discussion please provide solutions to real word use cases I mentioned above

[segevofer]

I actually agree with @artyil
This example also demonstrate the issue:

const url1 = new URLSearchParams({ foo: false, bar: '1' }) // <- FAILS
const url2 = new URLSearchParams({ foo: 'false', bar: '1' }) // <- OK

The spec of URLSearchParams doesn't specify the value type of that object,

Forcing code like this, is too strict, and weird:

const url1 = new URLSearchParams({ foo: false.toString() })

So it should support string|number|boolean

[BMCooley]

I largely agree with @nmain that the automatic coercion of non-strings to strings that exists in many DOM apis is very implicit and typescript should NOT cater to those implicit coercions.

I'm not sure that applies here. Here we are creating a new URL object. I think we can agree that a URL is a specific type of string so passing nonString values to the constructor, append and set methods would be like calling a urlify method. You are explicitly asking for a standardized way of converting values to a url type value (string). Very similar to JSON.stringify, yes things are being casted but that's the core functionality of the method.

The underlying implementation just uses template literals to cast to a string. I'd be happy to make the pr to accept template-literable types as values here.

[OliverJAsh]

AFAICS, string coercion is not standardised as part of URLSearchParams, so the current types correctly reflect what is (currently) the standard.

constructor(optional (sequence<sequence<USVString>> or record<USVString, USVString> or USVString) init = "");

void set(USVString name, USVString value);

https://url.spec.whatwg.org/#idl-index

I would prefer URLSearchParams adheres to the standard (as it does now). If people want to allow coercion, they can easily compose/wrap URLSearchParams:

const myUrlSearchParams = (init: Record<string, string | number | boolean>) =>
  new URLSearchParams(init as Record<string, string>)

Maybe coercion will be added to the standard in the future, at which point I would expect the types to also be updated.

Not all string coercion is desired (e.g. objects/functions, null, undefined), so the current types will be useful in helping to catch those bugs.

[lucacasonato]

@RyanCavanaugh I don't think this is a bug, and thus the issue should be closed:

https://url.spec.whatwg.org/#ref-for-dom-urlsearchparams-urlsearchparams specifies that URLSearchParam takes a webidl union of sequence<sequence<USVString>> or record<USVString, USVString> or USVString. In the case specified by the OP the record<USVString, USVString> is used because the webidl union resolution determines that ECMA type of a literal object is "Object", it is not null, and it does not have a @@iterator property (see https://heycam.github.io/webidl/#es-union, mainly 8.2 and 8.4). The reason a number works, is because WebIDL specifies that everything but symbols should be coerced into a string (https://heycam.github.io/webidl/#es-USVString, https://heycam.github.io/webidl/#es-DOMString & https://tc39.es/ecma262/#sec-tostring). TypeScript typings do not usually reflect the coercible types, only the strict types. The strict type for the record value here is the string, thus typings for argument 1 of URLSearchParams should be string[][] | Record<string, string> | string (or [string, string][] | Record<string, string> | string).

If typings should also represent coercion states, we could type essentially all Web APIs as taking any because WebIDL is very lax 😉. Fun fact: for WebIDL the only invalid URLSearchParams constructor is new URLSearchParams(Symbol()), or other object or iterable types containing symbols.

[jimmywarting]

There are many valid DOM Api's that takes "any" as a valid argument and it bother me on so many levels that TypeScript treats it so strictly. Like: it should be totally fine to do: new Blob([{}]) if you want to for some reason or doing fetch(new URL(...)), new ArrayBuffer("23") and even omitting arguments in ArrayBuffer to allow for new ArrayBuffer()

Take this bit mask example that takes a bunch o boolean and turn it into a number

function createMask (...args: boolean[]) {
    var nMask = 0, nFlag = 0, nLen = args.length
    for (nFlag; nFlag < nLen; nMask |= args[nFlag] << nFlag++)
    return nMask
}

const isLoggedIn = true
const hasReadPermission = true
const hasWritePermission = false

createMask(isLoggedIn, hasReadPermission, hasWritePermission) // 3

TS is complaining that nFlag isn't a number, but it's totally fine to do bitwise operators on boolean to, cuz in the end boolean is just a 1 or a 0

The WebIDL dose so many things to converting xyz to the correct type that it needs. I think TS needs to better understand symbol.toPrimitive, toString and toJSON stuff and how webidl conversion works

[lucacasonato]

@jimmywarting Typescript treats USVString as a string because it is a string. It also treats ByteString or DOMString as a string, because they are also strings. There is nothing special about USVString in regards to type coercion. All types except Symbol can be coerced into USVString/DOMString/ByteString in WebIDL. I don't think typescript should represent this though, as the point of it is to prevent runtime coercion. new Blob([{}]) resulting in a blob with contents [object Object] is not something typescript should cater to IMO. It defeats the purpose of strict types.

So I don't think you agree with me, because I think this issue is invalid and should be closed as working as intended 😄

[ekwoka]

new Blob([{}]) resulting in a blob with contents [object Object] is not something typescript should cater to IMO. It defeats the purpose of strict types.

Little bit of a useless example, since nobody here is trying to make the argument it should accept any. Just that it can accept the core primitives as there are no similar gotchas like you're describing.

[JGJP]

Can we bring back this discussion? I think it's enough for it to accept primitives that we know can be converted to strings, and also any object that implements the toString() method with a string return type

[Kris-Pelteshki]

I can't believe the TS team seriously went with this decision.
As an enthusiastic TS strict user, I would much rather do new URLSearchParams(({take: 15, color: false}) as any)
Instead of doing things like false.ToString()