Add Stringified

Author: swallez

compiler/src/model/utils.ts

@@ -215,6 +215,15 @@ export function modelType (node: Node): model.ValueOf {
       return type
     }
 
+    case ts.SyntaxKind.PrefixUnaryExpression: {
+      // Negative number
+      const type: model.LiteralValue = {
+        kind: 'literal_value',
+        value: Number(node.getText())
+      }
+      return type
+    }
+
     case ts.SyntaxKind.TypeParameter: {
       assert(node, Node.isTypeParameterDeclaration(node), `The node is not of type ${ts.SyntaxKind[ts.SyntaxKind.TypeReference]} but ${ts.SyntaxKind[node.getKind()]} instead`)
       const name = node.compilerNode.getText()

docs/modeling-guide.md

@@ -160,9 +160,9 @@ The `Date` type in TypeScript refers to the JavaScript `Date` object,
 since Elasticsearch needs a string or a numeric value, there are aliases also for date types:
 
 ```ts
-type Timestamp = string
+type DateTime = string
 type TimeSpan = string
-type DateString = string
+type DateTime = string
 ```
 
 ### Binary
@@ -230,6 +230,31 @@ class Response {
 }
 ```
 
+### Stringified values
+
+Elasticsearch sometimes uses string-only representations in the JSON it outputs, even for numbers and booleans. This is notably seen in `cat` request and index and cluster settings.
+
+To keep the semantic soundness of the specification and avoid adding ` | string` to handle these cases, the `Stringified` behaviour should be used for these cases. Also, this problem only affects output: data should be sent in its original format (i.e. number, boolean, etc).
+
+Instead of:
+```ts
+export class IndexSettings {
+  // DO NOT DO THAT
+  number_of_shards?: integer | string
+  number_of_replicas?: integer | string
+  hidden?: boolean | string
+}
+```
+
+Use the `Stringified` behavior:
+```
+export class IndexSettings {
+  number_of_shards?: Stringified<integer>
+  number_of_replicas?: Stringified<integer>
+  hidden?: Stringified<boolean>
+}
+```
+
 ### Variants
 
 Variants is a special syntax that can be used by language generators to understand

specification/_spec_utils/Stringified.ts

@@ -0,0 +1,27 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Some APIs will return values such as numbers also as a string (notably epoch timestamps). This behavior
+ * is used to capture this behavior while keeping the semantics of the field type.
+ *
+ * Depending on the target language, code generators can keep the union or remove it and leniently parse
+ * strings to the target type.
+ */
+export type Stringified<T> = T | string