Add support for non exhaustive variants (#1662)

Author: swallez

compiler/src/model/metamodel.ts

@@ -177,19 +177,28 @@ export abstract class BaseType {
 
 export type Variants = ExternalTag | InternalTag | Container
 
-export class ExternalTag {
+export class VariantBase {
+  /**
+   * Is this variant type open to extensions? Default to false. Used for variants that can
+   * be extended with plugins. If true, target clients should allow for additional variants
+   * with a variant tag outside the ones defined in the spec and arbitrary data as the value.
+   */
+  nonExhaustive?: boolean
+}
+
+export class ExternalTag extends VariantBase {
   kind: 'external_tag'
 }
 
-export class InternalTag {
+export class InternalTag extends VariantBase {
   kind: 'internal_tag'
   /* Name of the property that holds the variant tag */
   tag: string
   /* Default value for the variant tag if it's missing */
   defaultTag?: string
 }
 
-export class Container {
+export class Container extends VariantBase {
   kind: 'container'
 }
 
@@ -322,6 +331,11 @@ export class EnumMember {
  */
 export class Enum extends BaseType {
   kind: 'enum'
+  /**
+   * If the enum is open, it means that other than the specified values it can accept an arbitrary value.
+   * If this property is not present, it means that the enum is not open (in other words, is closed).
+   */
+  isOpen?: boolean
   members: EnumMember[]
 }
 

compiler/src/model/utils.ts

@@ -414,7 +414,7 @@ export function modelGenerics (node: TypeParameterDeclaration): string {
  * which returns an array that only contains the member of the Enum.
  */
 export function modelEnumDeclaration (declaration: EnumDeclaration): model.Enum {
-  return {
+  const type: model.Enum = {
     specLocation: sourceLocation(declaration),
     name: {
       name: declaration.getName(),
@@ -433,6 +433,13 @@ export function modelEnumDeclaration (declaration: EnumDeclaration): model.Enum
         return member
       })
   }
+
+  const tags = parseJsDocTags(declaration.getJsDocs())
+  if (typeof tags.non_exhaustive === 'string') {
+    type.isOpen = true
+  }
+
+  return type
 }
 
 /**
@@ -632,7 +639,7 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
   // We want to enforce a single jsDoc block.
   assert(jsDocs, jsDocs.length < 2, 'Use a single multiline jsDoc block instead of multiple single line blocks')
 
-  const validTags = ['class_serializer', 'doc_url', 'doc_id', 'behavior', 'variants', 'variant', 'shortcut_property', 'codegen_names']
+  const validTags = ['class_serializer', 'doc_url', 'doc_id', 'behavior', 'variants', 'variant', 'shortcut_property', 'codegen_names', 'non_exhaustive']
   const tags = parseJsDocTags(jsDocs)
   if (jsDocs.length === 1) {
     const description = jsDocs[0].getDescription()
@@ -650,6 +657,8 @@ export function hoistTypeAnnotations (type: model.TypeDefinition, jsDocs: JSDoc[
       }
     } else if (tag === 'variants') {
     } else if (tag === 'variant') {
+    } else if (tag === 'non_exhaustive') {
+      assert(jsDocs, typeof tags.variants === 'string', '@non_exhaustive only applies to enums and @variants')
     } else if (tag === 'doc_url') {
       assert(jsDocs, isValidUrl(value), '@doc_url is not a valid url')
       type.docUrl = value
@@ -924,13 +933,21 @@ export function parseVariantsTag (jsDoc: JSDoc[]): model.Variants | undefined {
     return undefined
   }
 
+  const nonExhaustive = (typeof tags.non_exhaustive === 'string') ? true : undefined
+
   const [type, ...values] = tags.variants.split(' ')
   if (type === 'external') {
-    return { kind: 'external_tag' }
+    return {
+      kind: 'external_tag',
+      nonExhaustive: nonExhaustive
+    }
   }
 
   if (type === 'container') {
-    return { kind: 'container' }
+    return {
+      kind: 'container',
+      nonExhaustive: nonExhaustive
+    }
   }
 
   assert(jsDoc, type === 'internal', `Bad variant type: ${type}`)
@@ -940,6 +957,7 @@ export function parseVariantsTag (jsDoc: JSDoc[]): model.Variants | undefined {
 
   return {
     kind: 'internal_tag',
+    nonExhaustive: nonExhaustive,
     tag: pairs.tag,
     defaultTag: pairs.default
   }
@@ -972,13 +990,16 @@ export function parseCommaSeparated (value: string): string[] {
 
 /**
  * Parses an array of "key=value" pairs and validate key names. Values can optionally be enclosed with single
- * or double quotes.
+ * or double quotes. If there is only a key with no value (no '=') the value is set to 'true'
  */
 export function parseKeyValues (node: Node | Node[], pairs: string[], ...validKeys: string[]): Record<string, string> {
   const result = {}
   pairs.forEach(item => {
     const kv = item.split('=')
-    assert(node, kv.length === 2, 'Malformed key/value list')
+    assert(node, kv.length <= 2, 'Malformed key/value list')
+    if (kv.length === 1) {
+      kv.push('true')
+    }
     assert(node, validKeys.includes(kv[0]), `Unknown key '${kv[0]}'`)
     result[kv[0]] = kv[1].replace(/["']/g, '')
   })

docs/modeling-guide.md

@@ -96,6 +96,19 @@ enum Orientation {
 }
 ```
 
+Some enumerations can accept arbitrary values other than the ones defined. The `@non_exhaustive` jsdoc tag can be used to describe this behavior.
+By default, an enum is to be considered exhaustive.
+
+```ts
+/** @non_exhaustive */
+export enum ScriptLanguage {
+  painless,
+  expression,
+  mustache,
+  java
+}
+```
+
 ### User defined value
 
 Represents a value that will be defined by the user and has no specific type.
@@ -219,6 +232,11 @@ class Response {
 
 Variants is a special syntax that can be used by language generators to understand
 which type they will need to build based on the variant configuration.
+
+If the list of variants is not exhaustive (e.g. for types where new variants can be added by
+Elasticsearch plugins), you can add the `@non_exhaustive` js doc tag to indicate that additional
+variants can exist and should be accepted.
+
 There are three type of variants:
 
 #### Internal