Is a function signature with a parameter type `(DOMString or Interface)` a footgun?

[saschanaz]

What is the issue with the Web IDL Standard?

Context: https://bugzilla.mozilla.org/show_bug.cgi?id=2040944#c10, whatwg/fs#180

The File System PR adds this:

  Promise<undefined> move(USVString newEntryName);
  Promise<undefined> move(FileSystemDirectoryHandle destinationDirectory);
  Promise<undefined> move(FileSystemDirectoryHandle destinationDirectory, USVString newEntryName);

So .move("path as string") or .move(aDirectoryHandle). The problem happens with .move(aFileSystemFileHandle), because it's an interface instance but not a FileSystemDirectoryHandle, the parameter is silently eaten as a string, resulting [object FileSystemFileHandle] without any error.

Implicitly stringification has probably been always a footgun but this is even more footgun as you do expect either a string or a specific typed object here, any other object will cause a silent fire.

The suggested Gecko patch in the bug adds another signature to avoid this:

  // the only role of this signature ... is to throw an exception.
  Promise<undefined> move(FileSystemFileHandle aFileHandle);

I hate this, but can we do any better here?

[annevk]

It is, XMLHttpRequest's send() has this problem as well.

Perhaps we should make the coercion fallback explicit and opt new APIs out of it. But also in this case I think there's only one shipping implementation so maybe we can still change the shape of the API?

[annevk]

@linusg @ljharb what does TC39 for these kind of APIs?

[linusg]

We generally avoid coercion for any new APIs, obviously inconsistent with early language design choices but avoiding this kind of footgun. See https://github.com/tc39/how-we-work/blob/main/normative-conventions.md, in particular Avoid coercing arguments to types other than Boolean.

A recent similar example is Temporal, which often accepts either a string or Temporal object, e.g. https://tc39.es/proposal-temporal/#sec-temporal.plaindate.from / https://tc39.es/proposal-temporal/#sec-temporal-totemporaldate:

ToTemporalDate ( item [ , options ] )

1. If options is not present, set options to undefined.
2. If item is an Object, then
   a. If item has an [[InitializedTemporalDate]] internal slot, then [...]
   b. If item has an [[InitializedTemporalZonedDateTime]] internal slot, then [...]
   [...] (fallback for plain temporal-like objects)
3. If item is not a String, throw a TypeError exception.
   [...]

Or, if only a primitive is expected: https://tc39.es/ecma262/#sec-uint8array.frombase64

Uint8Array.fromBase64 ( string [ , options ] )

1. If string is not a String, throw a TypeError exception.
   [...]

My WebIDL is a bit rusty but I think having some sort of parameter attribute for new APIs that prefers throwing over coercion on type mismatch is worth exploring and would match the current direction of TC39 API surface.

[ljharb]

Echoing linus' comment - it's proven far better for DX to avoid coercion and throw rather than accept multiple kinds of things and try to guess at the user's intent.

[saschanaz]

We discussed this today again (as part of whatwg/fs#186) and agreed that having an extended attribute to prevent string coercion would be nice.

[annevk]

I think we should do the inverse although it will be a little bit more involved. Add [LegacyCoercion] to all places that perform coercion today. That will make it vastly more likely new APIs will never run into this issue.