Labeled tuples

package.json

@@ -36,6 +36,7 @@
     "@types/mocha": "^8.2.0",
     "@types/node": "^14.14.31",
     "@types/sinon": "^10.0.0",
+    "@types/sinon-chai": "^3.2.5",
     "benchmark": "^2.1.4",
     "catharsis": "^0.9.0",
     "chai": "^4.3.0",
@@ -47,6 +48,7 @@
     "rollup": "^2.39.0",
     "semantic-release": "^17.4.3",
     "sinon": "^10.0.0",
+    "sinon-chai": "^3.7.0",
     "ts-node": "^9.1.1",
     "ts-standard": "^10.0.0",
     "typedoc": "^0.20.24",
@@ -93,5 +95,7 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
   }
 }

src/assertTypes.ts

@@ -13,18 +13,27 @@ export function assertTerminal (result?: IntermediateResult): TerminalResult {
   return result
 }
 
-export function assertKeyValueOrTerminal (result: IntermediateResult): KeyValueResult | TerminalResult {
-  if (result.type === 'JsdocTypeKeyValue' && 'value' in result) {
-    return result
+export function assertPlainKeyValueOrTerminal (result: IntermediateResult): KeyValueResult | TerminalResult {
+  if (result.type === 'JsdocTypeKeyValue') {
+    return assertPlainKeyValue(result)
   }
   return assertTerminal(result)
 }
 
-export function assertKeyValueOrName (result: IntermediateResult): KeyValueResult | NameResult {
-  if (result.type === 'JsdocTypeKeyValue' && 'value' in result) {
+export function assertPlainKeyValueOrName (result: IntermediateResult): KeyValueResult | NameResult {
+  if (result.type === 'JsdocTypeName') {
     return result
-  } else if (result.type !== 'JsdocTypeName') {
-    throw new UnexpectedTypeError(result)
+  }
+  return assertPlainKeyValue(result)
+}
+
+export function assertPlainKeyValue (result: IntermediateResult): KeyValueResult {
+  if (!isPlainKeyValue(result)) {
+    if (result.type === 'JsdocTypeKeyValue') {
+      throw new UnexpectedTypeError(result, 'Expecting no left side expression.')
+    } else {
+      throw new UnexpectedTypeError(result)
+    }
   }
   return result
 }
@@ -41,3 +50,7 @@ export function assertNumberOrVariadicName (result: IntermediateResult): NumberR
   }
   return result
 }
+
+export function isPlainKeyValue (result: IntermediateResult): result is KeyValueResult {
+  return result.type === 'JsdocTypeKeyValue' && !result.meta.hasLeftSideExpression
+}

src/errors.ts

@@ -42,8 +42,12 @@ export class EarlyEndOfParseError extends Error {
 }
 
 export class UnexpectedTypeError extends Error {
-  constructor (result: IntermediateResult) {
-    super(`Unexpected type: '${result.type}'`)
+  constructor (result: IntermediateResult, message?: string) {
+    let error = `Unexpected type: '${result.type}'.`
+    if (message !== undefined) {
+      error += ` Message: ${message}`
+    }
+    super(error)
 
     Object.setPrototypeOf(this, UnexpectedTypeError.prototype)
   }

src/parslets/ArrowFunctionParslet.ts

@@ -2,7 +2,7 @@ import { InfixParslet } from './Parslet'
 import { TokenType } from '../lexer/Token'
 import { Precedence } from '../Precedence'
 import { BaseFunctionParslet } from './BaseFunctionParslet'
-import { assertKeyValueOrName } from '../assertTypes'
+import { assertPlainKeyValueOrName } from '../assertTypes'
 import { Parser } from '../Parser'
 import { FunctionResult } from '../result/TerminalResult'
 import { IntermediateResult } from '../result/IntermediateResult'
@@ -21,7 +21,7 @@ export class ArrowFunctionParslet extends BaseFunctionParslet implements InfixPa
 
     return {
       type: 'JsdocTypeFunction',
-      parameters: this.getParameters(left).map(assertKeyValueOrName),
+      parameters: this.getParameters(left).map(assertPlainKeyValueOrName),
       arrow: true,
       parenthesis: true,
       returnType: parser.parseType(Precedence.ALL)

src/parslets/BaseFunctionParslet.ts

@@ -1,5 +1,5 @@
 import { KeyValueResult, NonTerminalResult } from '../result/NonTerminalResult'
-import { assertKeyValueOrTerminal } from '../assertTypes'
+import { assertPlainKeyValueOrTerminal } from '../assertTypes'
 import { UnexpectedTypeError } from '../errors'
 import { IntermediateResult } from '../result/IntermediateResult'
 import { TerminalResult } from '../result/TerminalResult'
@@ -15,7 +15,7 @@ export class BaseFunctionParslet {
       throw new UnexpectedTypeError(value)
     }
 
-    return parameters.map(p => assertKeyValueOrTerminal(p))
+    return parameters.map(p => assertPlainKeyValueOrTerminal(p))
   }
 
   protected getUnnamedParameters (value: IntermediateResult): TerminalResult[] {

src/parslets/FunctionParslet.ts

@@ -61,7 +61,7 @@ export class FunctionParslet extends BaseFunctionParslet implements PrefixParsle
     } else {
       result.parameters = this.getParameters(value)
       for (const p of result.parameters) {
-        if (p.type === 'JsdocTypeKeyValue' && (!this.allowNamedParameters.includes(p.value) || p.meta.quote !== undefined)) {
+        if (p.type === 'JsdocTypeKeyValue' && (!this.allowNamedParameters.includes(p.key) || p.meta.quote !== undefined)) {
           throw new Error(`only allowed named parameters are ${this.allowNamedParameters.join(',')} but got ${p.type}`)
         }
       }

src/parslets/KeyValueParslet.ts

@@ -56,12 +56,13 @@ export class KeyValueParslet implements InfixParslet {
 
       return {
         type: 'JsdocTypeKeyValue',
-        value: left.value.toString(),
+        key: left.value.toString(),
         right: parser.parseType(Precedence.KEY_VALUE),
         optional: optional,
         readonly: readonlyProperty,
         meta: {
-          quote
+          quote,
+          hasLeftSideExpression: false
         }
       }
     } else {
@@ -74,7 +75,10 @@ export class KeyValueParslet implements InfixParslet {
       return {
         type: 'JsdocTypeKeyValue',
         left: assertTerminal(left),
-        right: parser.parseType(Precedence.KEY_VALUE)
+        right: parser.parseType(Precedence.KEY_VALUE),
+        meta: {
+          hasLeftSideExpression: true
+        }
       }
     }
   }

src/parslets/ObjectParslet.ts

@@ -54,12 +54,13 @@ export class ObjectParslet implements PrefixParslet {
 
           result.elements.push({
             type: 'JsdocTypeKeyValue',
-            value: field.value.toString(),
+            key: field.value.toString(),
             right: undefined,
             optional: optional,
             readonly: false,
             meta: {
-              quote
+              quote,
+              hasLeftSideExpression: false
             }
           })
         } else if (field.type === 'JsdocTypeKeyValue') {

src/parslets/ParameterListParslet.ts

@@ -1,7 +1,7 @@
 import { InfixParslet } from './Parslet'
 import { TokenType } from '../lexer/Token'
 import { Precedence } from '../Precedence'
-import { assertKeyValueOrTerminal } from '../assertTypes'
+import { assertPlainKeyValueOrTerminal } from '../assertTypes'
 import { NoParsletFoundError } from '../errors'
 import { Parser } from '../Parser'
 import { IntermediateResult, ParameterList } from '../result/IntermediateResult'
@@ -29,13 +29,13 @@ export class ParameterListParslet implements InfixParslet {
 
   parseInfix (parser: Parser, left: IntermediateResult): ParameterList {
     const elements: Array<TerminalResult|KeyValueResult> = [
-      assertKeyValueOrTerminal(left)
+      assertPlainKeyValueOrTerminal(left)
     ]
     parser.consume(',')
     do {
       try {
         const next = parser.parseIntermediateType(Precedence.PARAMETER_LIST)
-        elements.push(assertKeyValueOrTerminal(next))
+        elements.push(assertPlainKeyValueOrTerminal(next))
       } catch (e) {
         if (this.allowTrailingComma && e instanceof NoParsletFoundError) {
           break

src/parslets/ParenthesisParslet.ts

@@ -1,7 +1,7 @@
 import { PrefixParslet } from './Parslet'
 import { TokenType } from '../lexer/Token'
 import { Precedence } from '../Precedence'
-import { assertTerminal } from '../assertTypes'
+import { assertTerminal, isPlainKeyValue } from '../assertTypes'
 import { Parser } from '../Parser'
 import { ParenthesisResult } from '../result/TerminalResult'
 import { ParameterList } from '../result/IntermediateResult'
@@ -29,7 +29,7 @@ export class ParenthesisParslet implements PrefixParslet {
     }
     if (result.type === 'JsdocTypeParameterList') {
       return result
-    } else if (result.type === 'JsdocTypeKeyValue' && 'value' in result) {
+    } else if (result.type === 'JsdocTypeKeyValue' && isPlainKeyValue(result)) {
       return {
         type: 'JsdocTypeParameterList',
         elements: [result]

src/parslets/TupleParslet.ts

@@ -1,9 +1,10 @@
-import { assertTerminal } from '../assertTypes'
+import { assertPlainKeyValue, assertTerminal } from '../assertTypes'
 import { TokenType } from '../lexer/Token'
 import { Parser } from '../Parser'
 import { PrefixParslet } from './Parslet'
 import { Precedence } from '../Precedence'
 import { TupleResult } from '../result/TerminalResult'
+import { IntermediateResult } from '../result/IntermediateResult'
 
 interface TupleParsletOptions {
   allowQuestionMark: boolean
@@ -37,16 +38,24 @@ export class TupleParslet implements PrefixParslet {
 
     const typeList = parser.parseIntermediateType(Precedence.ALL)
     if (typeList.type === 'JsdocTypeParameterList') {
-      result.elements = typeList.elements.map(assertTerminal)
+      if (typeList.elements[0].type === 'JsdocTypeKeyValue') {
+        result.elements = typeList.elements.map(assertPlainKeyValue)
+      } else {
+        result.elements = typeList.elements.map(assertTerminal)
+      }
     } else {
-      result.elements = [assertTerminal(typeList)]
+      if (typeList.type === 'JsdocTypeKeyValue') {
+        result.elements = [assertPlainKeyValue(typeList)]
+      } else {
+        result.elements = [assertTerminal(typeList)]
+      }
     }
 
     if (!parser.consume(']')) {
       throw new Error('Unterminated \'[\'')
     }
 
-    if (!this.allowQuestionMark && result.elements.some(e => e.type === 'JsdocTypeUnknown')) {
+    if (!this.allowQuestionMark && result.elements.some((e: IntermediateResult) => e.type === 'JsdocTypeUnknown')) {
       throw new Error('Question mark in tuple not allowed')
     }
 

src/result/NonTerminalResult.ts

@@ -16,12 +16,13 @@ export type NonTerminalResult =
  */
 export interface KeyValueResult {
   type: 'JsdocTypeKeyValue'
-  value: string
+  key: string
   right: TerminalResult | undefined
   optional: boolean
   readonly: boolean
   meta: {
     quote: QuoteStyle | undefined
+    hasLeftSideExpression: false
   }
 }
 
@@ -34,6 +35,9 @@ export interface JsdocObjectKeyValueResult {
   type: 'JsdocTypeKeyValue'
   left: TerminalResult
   right: TerminalResult
+  meta: {
+    hasLeftSideExpression: true
+  }
 }
 
 export interface PropertyResult {

src/result/TerminalResult.ts

@@ -239,7 +239,7 @@ export interface ImportResult {
  */
 export interface TupleResult {
   type: 'JsdocTypeTuple'
-  elements: TerminalResult[]
+  elements: TerminalResult[]|KeyValueResult[]
 }
 
 /**

src/transforms/catharsisTransform.ts

@@ -1,5 +1,5 @@
 import { extractSpecialParams, notAvailableTransform, transform, TransformRules } from './transform'
-import { assertTerminal } from '../assertTypes'
+import { assertTerminal, isPlainKeyValue } from '../assertTypes'
 import { TerminalResult } from '../result/TerminalResult'
 import { quote } from './stringify'
 
@@ -239,10 +239,10 @@ const catharsisTransformRules: TransformRules<CatharsisParseResult> = {
   }),
 
   JsdocTypeKeyValue: (result, transform) => {
-    if ('value' in result) {
+    if (isPlainKeyValue(result)) {
       return {
         type: 'FieldType',
-        key: makeName(quote(result.value, result.meta.quote)),
+        key: makeName(quote(result.key, result.meta.quote)),
         value: result.right === undefined ? undefined : transform(result.right)
       }
     } else {