Update: Add support for BooleanLiteralType

[arv]

Both Flow and TypeScript (2.0) support boolean literals as types.

These are mostly used with unions as in:

type Result = {
  ok: true,
  value: string,
} | {
  ok: false,
}

[jquerybot]

Thank you for your pull request. It looks like this may be your first contribution to a jQuery Foundation project, if so we need you to sign our Contributor License Agreement (CLA).

📝 Please visit http://contribute.jquery.org/CLA/ to sign.

After you signed, the PR is checked again automatically after a minute. If there's still an issue, please reply here to let us know.

---

If you've already signed our CLA, it's possible your git author information doesn't match your CLA signature (both your name and email have to match), for more information, check the status of your CLA check.

[arv]

I signed the CLA yesterday...

[nzakas]

I'm sorry, I don't understand. How does this relate to JSDoc syntax?

[arv]

It is related to the type expression language that jsdoc uses. For example:

/**
 * @return {true}
 */
function alwaysTrue() {
  return true;
}

Silly example but when you combine it with @typedef and more complex types it is useful.

For some background:
https://flowtype.org/docs/dynamic-type-tests.html#tagged-unions
https://blogs.msdn.microsoft.com/typescript/2016/08/30/announcing-typescript-2-0-rc/

[nzakas]

I'm sorry, I'm having a hard time understanding. Why wouldn't you use boolean there? I don't see anything in those links that talks about JSDoc supporting this.

This utility is used by a lot of people, and I'm afraid can't stray from JSDoc expectations without some good justification or evidence that JSDoc supports what you're proposing here.

[arv]

Let me try to justify this:

• The type system for JSDoc should be able to express the type systems of Closure Compiler, TypeScript and Flow.
• Both TypeScript and Flow supports boolean literal types.
• Doctrine already support NumericLiteralType and StringLiteralType... it is just missing the boolean equivalent. Added support for numeric and string literal types (fixes #156) #172 added support for numeric and string literal types. You (@nzakas) then closed Support string/numeric/boolean literal types #156 without boolean support. This PR adds the missing boolean support.

[nzakas]

@arv #156 explained the use case and how JSDoc supports the syntax they were proposing. In my last comment, I asked for information showing how JSDoc works with this change. This is a JSDoc parsing tool, so the justification needs to be about JSDoc, not Flow or TypeScript.

If you'd like to provide an example JSDoc comment that makes use of this change, and explain how JSDoc handles using boolean literals instead of boolean, I'll be happy to evaluate this further.

[arv]

Ok. Here is is a less contrived example:

/**
 * @param {{ok: true, data: string} | {ok: false, error: Error}} result
 */
function handleResult(result) {
  if (result.ok) {
    print(result.data);
  } else {
    throw result.error;
  }
}

[nzakas]

And does that work with JSDoc without error?

If yes, please add that code in a unit test.

[arv]

@nzakas Thanks for getting back to me on this. I've updated the PR with a unit test that uses that complex type.

[arv]

What is the next step here?

[nzakas]

Sorry, lost track of this. It looks good. I'll merge it and cut a new release.

[arv]

Thanks @nzakas