{Type<type>} syntax fails on Node 12

[adroitwhiz]

In Node 12, bracketed type syntax like Array<number> or Object<string> fails with a parsing error.

Input code

/**
 * @returns {Array<number>}
 */
function doSomething() {
	return [1,2,3];
}

JSDoc configuration

This occurs independent of config.

JSDoc debug output

DEBUG: JSDoc 3.6.0 (Sat, 04 May 2019 22:43:05 GMT)
DEBUG: Environment info: {"env":{"conf":{"plugins":[],"recurseDepth":10,"source":{"includePattern":".+\\.js(doc|x)?$","excludePattern":"","include":["src"]},"sourceType":"module","tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},"templates":{"monospaceLinks":false,"cleverLinks":false}},"opts":{"_":[],"debug":true,"configure":".jsdoc.json","destination":"./out/","encoding":"utf8"}}}
DEBUG: Parsing source files: ["/home/adroitwhiz/Documents/jsdoctest/src/index.js"]
Parsing /home/adroitwhiz/Documents/jsdoctest/src/index.js ...
DEBUG: Finished parsing source files.
DEBUG: Adding inherited symbols, mixins, and interface implementations...
DEBUG: Adding borrowed doclets...
DEBUG: Post-processing complete.
Generating output files...
Error: unable to parse [ 'Array' ].<number>: Expected "!", "$", "'", "(", "*", ".", "...", "0", "?", "@", "Function", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase letter, or [1-9] but "[" found.
    at parseType (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/util/templateHelper.js:255:15)
    at buildLink (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/util/templateHelper.js:338:22)
    at exports.linkto (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/util/templateHelper.js:378:79)
    at /home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/templates/default/publish.js:119:25
    at Array.forEach (<anonymous>)
    at buildItemTypeStrings (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/templates/default/publish.js:118:25)
    at /home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/templates/default/publish.js:140:31
    at Array.forEach (<anonymous>)
    at addNonParamAttributes (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/templates/default/publish.js:139:11)
    at addSignatureReturns (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/templates/default/publish.js:175:23)
    at /home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/templates/default/publish.js:566:13
    at each (/home/adroitwhiz/Documents/jsdoctest/node_modules/taffydb/taffy.js:87:17)
    at Object.<anonymous> (/home/adroitwhiz/Documents/jsdoctest/node_modules/taffydb/taffy.js:1109:7)
    at Object.API.<computed> [as each] (/home/adroitwhiz/Documents/jsdoctest/node_modules/taffydb/taffy.js:127:18)
    at Object.exports.publish (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/templates/default/publish.js:554:12)
    at Object.module.exports.cli.generateDocs (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/cli.js:441:39)
Error: unable to parse [ 'Array' ].<number>: Expected "!", "$", "'", "(", "*", ".", "...", "0", "?", "@", "Function", "\"", "\\", "_", "break", "case", "catch", "class", "const", "continue", "debugger", "default", "delete", "do", "else", "enum", "export", "extends", "false", "finally", "for", "function", "if", "implements", "import", "in", "instanceof", "interface", "let", "new", "null", "package", "private", "protected", "public", "return", "static", "super", "switch", "this", "throw", "true", "try", "typeof", "undefined", "var", "void", "while", "with", "yield", "{", Unicode letter number, Unicode lowercase letter, Unicode modifier letter, Unicode other letter, Unicode titlecase letter, Unicode uppercase letter, or [1-9] but "[" found.
    at parseType (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/util/templateHelper.js:255:15)
    at buildLink (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/util/templateHelper.js:338:22)
    at Template.exports.linkto (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/util/templateHelper.js:378:79)
    at eval (eval at _.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1597:16), <anonymous>:11:14)
    at Array.forEach (<anonymous>)
    at Template.eval (eval at _.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1597:16), <anonymous>:9:10)
    at Template.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1604:21)
    at Template.partial (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/template.js:55:33)
    at Template.eval (eval at _.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1597:16), <anonymous>:17:14)
    at Template.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1604:21)
    at Template.partial (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/template.js:55:33)
    at eval (eval at _.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1597:16), <anonymous>:161:14)
    at Array.forEach (<anonymous>)
    at Template.eval (eval at _.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1597:16), <anonymous>:159:13)
    at Template.template (/home/adroitwhiz/Documents/jsdoctest/node_modules/underscore/underscore.js:1604:21)
    at Template.partial (/home/adroitwhiz/Documents/jsdoctest/node_modules/jsdoc/lib/jsdoc/template.js:55:33)

Expected behavior

Parsing should work.

Current behavior

It doesn't, as shown above.

Your environment

Software	Version
JSDoc	3.6.0
Node.js	12.0.0
npm	6.9.0
Operating system	Fedora Linux 29

[lll000111]

Problem

The source of the problem seems to be this line: https://github.com/jsdoc/jsdoc/blob/master/lib/jsdoc/tag/type.js#L200

The util.format function in node.js v12 indeed saw changes according to the changelog.

The input into the util.format is an array of the form ["ContainerType"] and a string "innerType".

I guess the %s in node.js's util.format originally just called the toString() method which turns ["item"] into "item", and now they seem to have extra code to add the "[....]" to arrays.

Confirming the suspicion in node.js REPL:

node.js v12:

> util.format( '%s.<%s>', ['item'], 'typeString')
"[ 'item' ].<typeString>"

node.js v10:

> util.format( '%s.<%s>', ['item'], 'typeString')
"item.<typeString>"

Solution

(At least for someone unfamiliar with the code and just playing around, not seeing the bigger picture, just trying to get this to run.)

In https://github.com/jsdoc/jsdoc/blob/master/lib/jsdoc/tag/type.js#L200 change the 2nd argument getTypeStrings(parsedType.expression) to getTypeStrings(parsedType.expression)[0] to extract the value from the array. This solves the problem for me.

[hegemonic]

@adroitwhiz, thanks for the bug report, and @lll000111, thanks for digging into the issue and identifying a fix. Working on this now.

[hegemonic]

Fixed in 3.6.1, which I just released.

[badgermole]

This thread is fairly old. Yet, I came across this same issue. I thought I was using the latest JSDoc - I can only see 3.5.5 on github. So mentions of 3.6.2 here surprised me. I added "jsdoc": "~3.6.2" to my package.json, and the issue is fixed. But my question is why does github only show 3.5.5?