Fix time-related types and properties (#1713)

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

@@ -156,14 +156,16 @@ feel free to add more if it feels appropriate!
 
 ### Dates
 
-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:
+Elasticsearch uses a lot of dates, times and durations. There are various types available to capture the variety of types and representations in the specification:
+
+* for date and time: `DateTime` for formatted dates, `EpochTime<UnitMillis>`, `EpochTime<UnitSeconds>`, etc. for number values
+* for intervals: `Duration` for formatted values, `DurationValue<UnitMillis>`, `DurationValue<UnitSeconds>`, etc. for number values
+* for time of day: `TimeOfDay
+
+See [`specification/_types/Time.ts`](../specification/_types/Time.ts) for additional details.
+
+Since code generators may choose to use a platform builtin type to represent time-related data, make sure to choose the appropriate representation and **never** use a primitive value such as `string` or `long`.
 
-```ts
-type Timestamp = string
-type TimeSpan = string
-type DateString = string
-```
 
 ### Binary
 
@@ -230,6 +232,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

docs/validation-example.md

@@ -69,7 +69,7 @@ open it with your favourite editor and perform the fix
      pipeline?: string;
      refresh?: Refresh;
      routing?: Routing;
-     timeout?: Time;
+     timeout?: Duration;
      version?: long;
      version_type?: VersionType;
      wait_for_active_shards?: string;