Use key-value-pairs instead of positional arguments

Author: flobernd

compiler/src/model/metamodel.ts

@@ -213,7 +213,7 @@ export class Container extends VariantBase {
 export class Inherits {
   type: TypeName
   generics?: ValueOf[]
-  meta?: string[]
+  meta?: { [p: string]: string }
 }
 
 /**

compiler/src/model/utils.ts

@@ -418,17 +418,25 @@ export function modelBehaviors (node: ExpressionWithTypeArguments, jsDocs: JSDoc
   const behaviorName = node.getExpression().getText()
   const generics = node.getTypeArguments().map(node => modelType(node))
 
-  let meta: string[] | undefined
+  let meta: Map<string, string> | undefined
   const tags = parseJsDocTagsAllowDuplicates(jsDocs)
   if (tags.behavior_meta !== undefined) {
-    // Splits a string by comma, but preserves comma in quoted strings
-    const re = /(?<=")[^"]+?(?="(?:\s*?,|\s*?$))|(?<=(?:^|,)\s*?)(?:[^,"\s][^,"]*[^,"\s])|(?:[^,"\s])(?![^"]*?"(?:\s*?,|\s*?$))(?=\s*?(?:,|$))/g
+    // Extracts whitespace/comma-separated key-value-pairs with a "=" delimiter and handles double-quotes
+    const re = /(?<key>[^=\s,]+)=(?<value>"([^"]*)"|([^\s,]+))/g
+
     for (const tag of tags.behavior_meta) {
       const id = tag.split(' ')
       if (id[0].trim() !== behaviorName) {
         continue
       }
-      meta = id.slice(1).join(' ').match(re) as string[]
+      const matches = [...id.slice(1).join(' ').matchAll(re)]
+      meta = new Map<string, string>()
+      for (const match of matches) {
+        if (match.groups == null) {
+          continue
+        }
+        meta.set(match.groups.key, match.groups.value.replace(/^"(.+(?="$))"$/, '$1'))
+      }
       break
     }
   }
@@ -439,7 +447,7 @@ export function modelBehaviors (node: ExpressionWithTypeArguments, jsDocs: JSDoc
       namespace: getNameSpace(node)
     },
     ...(generics.length > 0 && { generics }),
-    meta
+    meta: (meta === undefined) ? undefined : Object.fromEntries(meta)
   }
 }
 

compiler/src/steps/validate-model.ts

@@ -644,10 +644,10 @@ export default async function validateModel (apiModel: model.Model, restSpec: Ma
       for (const parent of typeDef.behaviors) {
         validateTypeRef(parent.type, parent.generics, openGenerics)
 
-        if (parent.type.name === 'AdditionalProperty' && (parent.meta == null || parent.meta.length < 2 || parent.meta.length > 3)) {
+        if (parent.type.name === 'AdditionalProperty' && (parent.meta == null || parent.meta.name == null || parent.meta.value == null)) {
           modelError(`AdditionalProperty behavior for type '${fqn(typeDef.name)}' requires a 'behavior_meta' decorator with at least 2 arguments (name of name, name of value, description)`)
         }
-        if (parent.type.name === 'AdditionalProperties' && (parent.meta == null || parent.meta.length !== 2)) {
+        if (parent.type.name === 'AdditionalProperties' && (parent.meta == null || parent.meta.name == null || parent.meta.description == null)) {
           modelError(`AdditionalProperties behavior for type '${fqn(typeDef.name)}' requires a 'behavior_meta' decorator with exactly 2 arguments (name, description)`)
         }
       }

docs/behaviors.md

@@ -16,7 +16,7 @@ We therefore document the requirement to behave like a dictionary for unknown pr
 
 ```ts
 /**
- * @behavior_meta AdditionalProperties sub_aggregations
+ * @behavior_meta AdditionalProperties name=sub_aggregations
  */
 class IpRangeBucket implements AdditionalProperties<AggregateName, Aggregate> {}
 ```
@@ -25,7 +25,7 @@ There are also many places where we expect only one runtime-defined property, su
 
 ```ts
 /**
- * @behavior_meta AdditionalProperty field, bounding_box
+ * @behavior_meta AdditionalProperty name=field value=bounding_box
  */
 class GeoBoundingBoxQuery extends QueryBase
   implements AdditionalProperty<Field, BoundingBox>

specification/_global/search/_types/suggester.ts

@@ -99,7 +99,7 @@ export class TermSuggestOption {
 }
 
 /**
- * @behavior_meta AdditionalProperties suggesters, "The named suggesters"
+ * @behavior_meta AdditionalProperties name=suggesters description="The named suggesters"
  */
 export class Suggester implements AdditionalProperties<string, FieldSuggester> {
   /** Global suggest text, to avoid repetition when the same text is used in several suggesters */

specification/_types/Errors.ts

@@ -26,7 +26,7 @@ import { AdditionalProperties } from '@spec_utils/behaviors'
  * Cause and details about a request failure. This class defines the properties common to all error types.
  * Additional details are also provided, that depend on the error type.
  *
- * @behavior_meta AdditionalProperties metadata, "Additional details about the error"
+ * @behavior_meta AdditionalProperties name=metadata description="Additional details about the error"
  */
 export class ErrorCause
   implements AdditionalProperties<string, UserDefinedValue>

specification/_types/aggregations/Aggregate.ts

@@ -331,7 +331,7 @@ export class MultiBucketAggregateBase<TBucket> extends AggregateBase {
 /**
  * Base type for multi-bucket aggregation results that can hold sub-aggregations results.
  *
- * @behavior_meta AdditionalProperties aggregations, "Nested aggregations"
+ * @behavior_meta AdditionalProperties name=aggregations description="Nested aggregations"
  */
 export class MultiBucketBase
   implements AdditionalProperties<AggregateName, Aggregate>
@@ -475,7 +475,7 @@ export class MultiTermsBucket extends MultiBucketBase {
 /**
  * Base type for single-bucket aggregation results that can hold sub-aggregations results.
  *
- * @behavior_meta AdditionalProperties aggregations, "Nested aggregations"
+ * @behavior_meta AdditionalProperties name=aggregations description="Nested aggregations"
  */
 export class SingleBucketAggregateBase
   extends AggregateBase
@@ -662,7 +662,7 @@ export class TopHitsAggregate extends AggregateBase {
 
 /**
  * @variant name=inference
- * @behavior_meta AdditionalProperties data, "Additional data"
+ * @behavior_meta AdditionalProperties name=data description="Additional data"
  */
 // This is a union with widely different fields, many of them being runtime-defined. We mimic below the few fields
 // present in `ParsedInference` with an additional properties spillover to not loose any data.

specification/_types/common.ts

@@ -318,7 +318,7 @@ export enum WaitForEvents {
 }
 
 /**
- * @behavior_meta AdditionalProperties metadata, "Document metadata"
+ * @behavior_meta AdditionalProperties name=metadata description="Document metadata"
  */
 // Additional properties are the meta fields
 export class InlineGet<TDocument>

specification/_types/query_dsl/compound.ts

@@ -180,21 +180,21 @@ export class DecayFunctionBase {
 }
 
 /**
- * @behavior_meta AdditionalProperty field, placement
+ * @behavior_meta AdditionalProperty name=field value=placement
  */
 export class NumericDecayFunction
   extends DecayFunctionBase
   implements AdditionalProperty<Field, DecayPlacement<double, double>> {}
 
 /**
- * @behavior_meta AdditionalProperty field, placement
+ * @behavior_meta AdditionalProperty name=field value=placement
  */
 export class DateDecayFunction
   extends DecayFunctionBase
   implements AdditionalProperty<Field, DecayPlacement<DateMath, Duration>> {}
 
 /**
- * @behavior_meta AdditionalProperty field, placement
+ * @behavior_meta AdditionalProperty name=field value=placement
  */
 export class GeoDecayFunction
   extends DecayFunctionBase

specification/_types/query_dsl/geo.ts

@@ -30,7 +30,7 @@ import { FieldLookup, QueryBase } from './abstractions'
 import { Field } from '@_types/common'
 
 /**
- * @behavior_meta AdditionalProperty field, bounding_box
+ * @behavior_meta AdditionalProperty name=field value=bounding_box
  */
 export class GeoBoundingBoxQuery
   extends QueryBase
@@ -58,7 +58,7 @@ export enum GeoExecution {
 }
 
 /**
- * @behavior_meta AdditionalProperty field, location
+ * @behavior_meta AdditionalProperty name=field value=location
  */
 export class GeoDistanceQuery
   extends QueryBase
@@ -96,7 +96,7 @@ export class GeoPolygonPoints {
 
 /**
  * @deprecated 7.12.0 Use geo-shape instead.
- * @behavior_meta AdditionalProperty field, polygon
+ * @behavior_meta AdditionalProperty name=field value=polygon
  */
 export class GeoPolygonQuery
   extends QueryBase
@@ -126,7 +126,7 @@ export class GeoShapeFieldQuery {
 }
 
 /**
- * @behavior_meta AdditionalProperty field, shape
+ * @behavior_meta AdditionalProperty name=field value=shape
  */
 // GeoShape query doesn't follow the common pattern of having a single field-name property
 // holding also the query base fields (boost and _name)

specification/_types/query_dsl/specialized.ts

@@ -340,7 +340,7 @@ export class ScriptScoreQuery extends QueryBase {
 }
 
 /**
- * @behavior_meta AdditionalProperty field, shape
+ * @behavior_meta AdditionalProperty name=field value=shape
  */
 // Shape query doesn't follow the common pattern of having a single field-name property
 // holding also the query base fields (boost and _name)

specification/_types/query_dsl/term.ts

@@ -252,7 +252,7 @@ export class TermQuery extends QueryBase {
 }
 
 /**
- * @behavior_meta AdditionalProperty field, term
+ * @behavior_meta AdditionalProperty name=field value=term
  */
 export class TermsQuery
   extends QueryBase

specification/_types/sort.ts

@@ -57,7 +57,7 @@ export class ScoreSort {
 }
 
 /**
- * @behavior_meta AdditionalProperty field, location
+ * @behavior_meta AdditionalProperty name=field value=location
  */
 export class GeoDistanceSort
   implements AdditionalProperty<Field, GeoLocation | GeoLocation[]>
@@ -86,7 +86,7 @@ export enum ScriptSortType {
 /**
  * @doc_id sort-search-results
  * @variants container
- * @behavior_meta AdditionalProperty field, sort
+ * @behavior_meta AdditionalProperty name=field value=sort
  */
 export class SortOptions implements AdditionalProperty<Field, FieldSort> {
   _score?: ScoreSort

specification/indices/_types/IndexSettings.ts

@@ -69,7 +69,7 @@ export class RetentionLease {
 /**
  * @doc_id index-modules-settings
  *
- * @behavior_meta AdditionalProperties other_settings, "Additional settings not covered in this type.
+ * @behavior_meta AdditionalProperties name=other_settings description="Additional settings not covered in this type."
  */
 export class IndexSettings
   implements AdditionalProperties<string, UserDefinedValue>

specification/indices/analyze/types.ts

@@ -50,7 +50,7 @@ export class CharFilterDetail {
 
 // Additional properties are attributes that can be set by plugin-defined tokenizers
 /**
- * @behavior_meta AdditionalProperties attributes, "Additional tokenizer-specific attributes"
+ * @behavior_meta AdditionalProperties name=attributes description="Additional tokenizer-specific attributes"
  */
 export class ExplainAnalyzeToken
   implements AdditionalProperties<string, UserDefinedValue>

specification/indices/field_usage_stats/IndicesFieldUsageStatsResponse.ts

@@ -30,7 +30,7 @@ export class Response {
 }
 
 /**
- * @behavior_meta AdditionalProperties stats, "Per index statistics"
+ * @behavior_meta AdditionalProperties name=stats description="Per index statistics"
  */
 export class FieldsUsageBody
   implements AdditionalProperties<IndexName, UsageStatsIndex>

specification/indices/shard_stores/types.ts

@@ -28,7 +28,7 @@ export class IndicesShardStores {
 }
 
 /**
- * @behavior_meta AdditionalProperty node_id, node
+ * @behavior_meta AdditionalProperty name=node_id value=node
  */
 export class ShardStore implements AdditionalProperty<NodeId, ShardStoreNode> {
   allocation: ShardStoreAllocation

specification/ingest/simulate/types.ts

@@ -57,7 +57,7 @@ export class Document {
 /**
  * The simulated document, with optional metadata.
  *
- * @behavior_meta AdditionalProperties metadata, "Additional metadata"
+ * @behavior_meta AdditionalProperties name=metadata description="Additional metadata"
  */
 export class DocumentSimulation
   implements AdditionalProperties<string, string>

specification/nodes/info/types.ts

@@ -171,7 +171,7 @@ export class NodeInfoRepositoriesUrl {
 }
 
 /**
- * @behavior_meta AdditionalProperties settings, "Additional or alternative settings"
+ * @behavior_meta AdditionalProperties name=settings description="Additional or alternative settings"
  */
 export class NodeInfoDiscover
   implements AdditionalProperties<string, UserDefinedValue>

specification/watcher/_types/Conditions.ts

@@ -30,7 +30,7 @@ export class ArrayCompareOpParams {
 }
 
 /**
- * @behavior_meta AdditionalProperty operator, params
+ * @behavior_meta AdditionalProperty name=operator value=params
  */
 export class ArrayCompareCondition
   implements AdditionalProperty<ConditionOp, ArrayCompareOpParams>

typescript-generator/src/metamodel.ts

@@ -213,7 +213,7 @@ export class Container extends VariantBase {
 export class Inherits {
   type: TypeName
   generics?: ValueOf[]
-  meta?: string[]
+  meta?: { [p: string]: string }
 }
 
 /**