Update definition of TypeError to reflect its broader usage

[domenic]

See https://esdiscuss.org/topic/exception-type-for-invalid-operations for background. I'd like to update the definition of TypeError (currently "Indicates the actual type of an operand is different than the expected type.") to something that more accurately explains how it is used as the catch-all fallback error.

Here's some possible wordings. We can wordsmith in this issue thread then I'll do a PR:

• Indicates that something went wrong, often related to the input to a function.
• Indicates that something went wrong, often related to the input to a function or the conditions under which it was called.
• Indicates that the wrong kind of thing was directly or indirectly passed to a function.
• Indicates the actual type of an operand is different than the expected type. Also used as a generic "fallback" type of error in situations when other more specific types are not appropriate.

[ljharb]

I've never understood the reasons why the spec doesn't include more specific error types that everybody can leverage. Would that not be a better approach than explicitly encouraging TypeError be used in a generic fashion?

[ljharb]

I've never understood the reasons why the spec doesn't include more specific error types that everybody can leverage. Would that not be a better approach than explicitly encouraging TypeError be used in a generic fashion?

[domenic]

@ljharb did you read the linked thread? It goes through that in some detail.

Regardless, the fact remains that TypeError is used for a lot more cases, so we should update its description to match.

[domenic]

@ljharb did you read the linked thread? It goes through that in some detail.

Regardless, the fact remains that TypeError is used for a lot more cases, so we should update its description to match.

[ljharb]

I didn't yet - i will, thanks. Fair point - whether it's overused or not, it's still used, so your original point is totes valid

[ljharb]

I didn't yet - i will, thanks. Fair point - whether it's overused or not, it's still used, so your original point is totes valid

[bterlson]

I don't really love any of the proposals - too wordy without giving solid guidance. How about:

Indicates that an invalid operation has occurred.

"Invalid operation" is synonymous with the current definition if one uses a very loose definition of type. So I think this is really just a clarification. I think covers both all current usages in the spec as well as the "writing to closed stream" scenario and general incorrect usage errors.

[bterlson]

I don't really love any of the proposals - too wordy without giving solid guidance. How about:

Indicates that an invalid operation has occurred.

"Invalid operation" is synonymous with the current definition if one uses a very loose definition of type. So I think this is really just a clarification. I think covers both all current usages in the spec as well as the "writing to closed stream" scenario and general incorrect usage errors.

[allenwb]

One purpose of that description is to provide guidance as to when it should be chosen. In particular, when TypeError be used instead of RangeError . From that perspective how about:

Indicates an operation could not be performed because the wrong kind of information was passed to it.

[allenwb]

One purpose of that description is to provide guidance as to when it should be chosen. In particular, when TypeError be used instead of RangeError . From that perspective how about:

Indicates an operation could not be performed because the wrong kind of information was passed to it.

[bterlson]

"Indicates an operation could not be performed" seems identical to "Indicates that an invalid operation has occurred" and I'm ok with either (but lead toward the latter as it matches the tense of existing definitions). You suggest further adding the notion that type error should be used in cases where "passing" is involved, but to me that seems superfluous and potentially confusing - if I had an API that didn't take any input at all, checked some global flag, and threw an error if its true, such an API should probably use a TypeError.

[bterlson]

"Indicates an operation could not be performed" seems identical to "Indicates that an invalid operation has occurred" and I'm ok with either (but lead toward the latter as it matches the tense of existing definitions). You suggest further adding the notion that type error should be used in cases where "passing" is involved, but to me that seems superfluous and potentially confusing - if I had an API that didn't take any input at all, checked some global flag, and threw an error if its true, such an API should probably use a TypeError.

[allenwb]

Invalid operation, to me, suggests something more akin to "non-existent operation" as opposed to an operation that could not be completed ("performed') because it was asked to operate upon the wrong kind of data. By "passed" I didn't necessary mean via function parameters, I meant any data that the operation needs to access or use so that includes global flags.

But, perhaps the answer is "TypeError is used to indicate an unsuccessful operation when none of the other NativeError objects are an appropriate indication of the failure cause."

[allenwb]

Invalid operation, to me, suggests something more akin to "non-existent operation" as opposed to an operation that could not be completed ("performed') because it was asked to operate upon the wrong kind of data. By "passed" I didn't necessary mean via function parameters, I meant any data that the operation needs to access or use so that includes global flags.

But, perhaps the answer is "TypeError is used to indicate an unsuccessful operation when none of the other NativeError objects are an appropriate indication of the failure cause."

[domenic]

TypeError is used to indicate an unsuccessful operation when none of the other NativeError objects are an appropriate indication of the failure cause.

I like this. I was trying to get at it with my

Indicates that something went wrong, often related to the input to a function.

and

Indicates the actual type of an operand is different than the expected type. Also used as a generic "fallback" type of error in situations when other more specific types are not appropriate.

[domenic]

TypeError is used to indicate an unsuccessful operation when none of the other NativeError objects are an appropriate indication of the failure cause.

I like this. I was trying to get at it with my

Indicates that something went wrong, often related to the input to a function.

and

Indicates the actual type of an operand is different than the expected type. Also used as a generic "fallback" type of error in situations when other more specific types are not appropriate.

[bterlson]

👍 to @allenwb's prose.

[bterlson]

👍 to @allenwb's prose.