jsdoc: Optional function parameters don't have optional type within function definition

[rschristian]

🔎 Search Terms

jsdoc optional parameters

🕗 Version & Regression Information

• This is the behavior in every version I tried, and I reviewed the FAQ for entries about jsdoc. It seems the intention is to support this behavior, per the handbook -- jsdoc supported types listing it as an example.

⏯ Playground Link

https://www.typescriptlang.org/play/?ts=5.2.2&ssl=10&ssc=2&pln=1&pc=1&filetype=js#code/PQKhCgAIUgBAHAhgJ0QW0gbwM4BdkCWAdgOYC+kk8AjJALSQCCkehpVK6AdFDApxhz5iJALwV4AJnpMikAPbxcBeUUQAbDqgwAKAOLz5JdQFNIAYXXzsAV2RnsATyK5EADwCUvOEm1ZWIhQA2vAAzAC6MoxE8rgAFibICkoqapq+6JA6AFIAygAi8gDGLM6unjzQPgL+wqTB8AAsogBEuCZ4LZEM0cnKqhpamQDuBPGQiJAAJiYAZog26riQAG4aNibesPa4dkTYtWzkkAAqcQQHF5DxZva2S7zA4LM2REX9cgGk2Ll1JL9HbA6GgAGiokjBYUhjQ8WCglCooXAZCAA

💻 Code

/**
 * @param {string}  p1 - A string param.
 * @param {string=} p2 - An optional param (Google Closure syntax)
 * @param {string} [p3] - Another optional param (JSDoc syntax).
 * @param {string} [p4="test"] - An optional param with a default value
 * @returns {string} This is the result
 */
function stringsStringStrings(p1, p2, p3, p4) {
    p3
}

🙁 Actual behavior

Within the definition of stringsStringsStrings(), p3 has an incorrect type of string.

🙂 Expected behavior

The parameter is optional, the type should be string | undefined.

Additional information about the issue

No response

[RyanCavanaugh]

You have to turn on strictNullChecks for the undefined type to exist in the first place. Once you do that, it works:

[rschristian]

Well damn:

When strictNullChecks is false, null and undefined are effectively ignored by the language.

Weird design choice, seeing as how "strict" here means "adhere to the underlying language spec", but I can work with it I guess. Thanks, sorry for the dumb question!

[MartinJohns]

Weird design choice, seeing as how "strict" here means "adhere to the underlying language spec"

The "underlying language spec" did not have an undefined type, and undefined was a valid value for number. TypeScript 2.0 changed this by adding a new optional feature, making the language more strict.

[rschristian]

The "underlying language spec" did not have an undefined type

Er, what? undefined is certainly one of JS's defined primitive data types.

undefined was a valid value for number.

Well that's interesting though equally bizarre.

[MartinJohns]

Er, what? undefined is certainly one of JS's defined primitive data types.

Talking about TypeScript here. Same applies to null, which is not one of JS's types.

Well that's interesting though equally bizarre.

It isn't, really. Both null and undefined were not valid types, and the values were assignable to every other type. This was then changed with the strictNullChecks feature of 2.0, but to avoid breaking changes in existing code it was made opt-in.

See also: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#null--and-undefined-aware-types

[rschristian]

Talking about TypeScript here.

And I was referring to JS, as it's the underlying language and actually has a language spec.

Well that's interesting though equally bizarre.
It isn't, really. Both null and undefined were not valid types, and the values were assignable to every other type.

It certainly is, and I'm not quite sure why you're bothering to rationalize it? Obviously that was a mistake and a huge divergence, the fix to which couldn't be stomached, so we got a flag. Pretending undefined and null don't exist in a language where they're spec'd primitives is, objectively, bizarre.

That's perfectly fine of course, software is what it is and we all make do all the time. Not trying to complain or criticize at all, just bewildered.