Implement OrderedDictionary<K, V> type

Author: flobernd

compiler/src/model/metamodel.ts

@@ -88,6 +88,7 @@ export class DictionaryOf {
   key: ValueOf
   value: ValueOf
   singleKey: boolean
+  ordered: boolean
 }
 
 /**

compiler/src/model/utils.ts

@@ -281,7 +281,8 @@ export function modelType (node: Node): model.ValueOf {
             kind: 'dictionary_of',
             key,
             value,
-            singleKey: false
+            singleKey: false,
+            ordered: false
           }
           return type
         }
@@ -294,7 +295,21 @@ export function modelType (node: Node): model.ValueOf {
             kind: 'dictionary_of',
             key,
             value,
-            singleKey: true
+            singleKey: true,
+            ordered: false
+          }
+          return type
+        }
+
+        case 'OrderedDictionary': {
+          assert(node, node.getTypeArguments().length === 2, 'A OrderedDictionary must have two arguments')
+          const [key, value] = node.getTypeArguments().map(node => modelType(node))
+          const type: model.DictionaryOf = {
+            kind: 'dictionary_of',
+            key,
+            value,
+            singleKey: false,
+            ordered: true
           }
           return type
         }
@@ -500,7 +515,7 @@ export function modelEnumDeclaration (declaration: EnumDeclaration): model.Enum
   }
 
   if (typeof tags.es_quirk === 'string') {
-    type.esQuirk = tags.es_quirk
+    type.esQuirk = tags.es_quirk.replace(/\r/g, '')
   }
 
   return type
@@ -892,7 +907,7 @@ function hoistPropertyAnnotations (property: model.Property, jsDocs: JSDoc[]): v
       assert(jsDocs, value === 'container_property', `Unknown 'variant' value '${value}' on property ${property.name}`)
       property.containerProperty = true
     } else if (tag === 'es_quirk') {
-      property.esQuirk = value
+      property.esQuirk = value.replace(/\r/g, '')
     } else {
       assert(jsDocs, false, `Unhandled tag: '${tag}' with value: '${value}' on property ${property.name}`)
     }

compiler/src/steps/validate-model.ts

@@ -396,17 +396,17 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
     const inheritedProps = inheritedProperties(typeDef)
 
     context.push('path')
-    validateProperties(typeDef.path, openGenerics, inheritedProps)
+    validateProperties(fqn(typeDef.name), typeDef.path, openGenerics, inheritedProps)
     context.pop()
 
     context.push('query')
-    validateProperties(typeDef.query, openGenerics, inheritedProps)
+    validateProperties(fqn(typeDef.name), typeDef.query, openGenerics, inheritedProps)
     context.pop()
 
     context.push('body')
     switch (typeDef.body.kind) {
       case 'properties':
-        validateProperties(typeDef.body.properties, openGenerics, inheritedProps)
+        validateProperties(fqn(typeDef.name), typeDef.body.properties, openGenerics, inheritedProps)
         break
       case 'value':
         validateValueOf(typeDef.body.value, openGenerics)
@@ -433,7 +433,7 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
 
     switch (typeDef.body.kind) {
       case 'properties':
-        validateProperties(typeDef.body.properties, openGenerics, inheritedProperties(typeDef))
+        validateProperties(fqn(typeDef.name), typeDef.body.properties, openGenerics, inheritedProperties(typeDef))
         break
       case 'value':
         validateValueOf(typeDef.body.value, openGenerics)
@@ -507,7 +507,7 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
 
     validateInherits(typeDef.inherits, openGenerics)
     validateBehaviors(typeDef, openGenerics)
-    validateProperties(typeDef.properties, openGenerics, inheritedProperties(typeDef))
+    validateProperties(fqn(typeDef.name), typeDef.properties, openGenerics, inheritedProperties(typeDef))
 
     if (typeDef.variants?.kind === 'container') {
       const variants = typeDef.properties.filter(prop => !(prop.containerProperty ?? false))
@@ -747,7 +747,7 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
     return false
   }
 
-  function validateProperties (props: model.Property[], openGenerics: Set<string>, inheritedProperties: Set<string>): void {
+  function validateProperties (type: string, props: model.Property[], openGenerics: Set<string>, inheritedProperties: Set<string>): void {
     const allIdentifiers = new Set<string>()
     const allNames = new Set<string>()
 
@@ -773,6 +773,13 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
       }
 
       context.push(`Property '${prop.name}'`)
+
+      if (prop.type.kind === 'dictionary_of' && prop.type.ordered) {
+        if (prop.name !== 'aggregations') {
+          modelError(`OrderedDictionary can not be used for property '${prop.name}' on type '${type}'.`)
+        }
+      }
+
       validateValueOf(prop.type, openGenerics)
       validateValueOfJsonEvents(prop.type)
       context.pop()

compiler/src/transform/expand-generics.ts

@@ -359,7 +359,8 @@ export function expandGenerics (inputModel: Model, config?: ExpansionConfig): Mo
           kind: 'dictionary_of',
           key: expandValueOf(value.key, mappings),
           value: expandValueOf(value.value, mappings),
-          singleKey: value.singleKey
+          singleKey: value.singleKey,
+          ordered: value.ordered
         }
 
       case 'instance_of': {

docs/modeling-guide.md

@@ -24,10 +24,24 @@ For example:
 ```json
 {
   "property1": "type",
-  "property2": "other-type",
+  "property2": "other-type"
 }
 ```
 
+### OrderedDictionary
+
+Represents a dynamic key value map that preserves the order of items:
+
+```ts
+property: OrderedDictionary<string, TypeDefinition>
+```
+
+The JSON specification and most dictionary implementations do not make guarantees about item ordering. 
+`OrderedDictionary` can be used to express this fact in the Elasticsearch specification.
+
+> [!WARNING]
+> This type should only be used for legacy types and should otherwise be avoided as far as possible.
+
 ### SingleKeyDictionary
 
 Represents a dynamic key value map with a single top level key: