Skip to content

Commit

Permalink
Added style guide (#89)
Browse files Browse the repository at this point in the history
  • Loading branch information
delvedor authored Jan 27, 2021
1 parent 825d8c6 commit 96062d3
Show file tree
Hide file tree
Showing 1,459 changed files with 7,462 additions and 9,175 deletions.
1 change: 1 addition & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Please make sure to follow the steps below when opening a pr:
- Tag the relative issue (if any) and give a brief explanation on what your changes are doing
- If you did a spec change, remember to generate again the outputs, you can do it by running `make generate-spec`
- Make sure your code follows the lint rules, you can fix them by running `npm run lint:fix --prefix specification`
- Sign the CLA https://www.elastic.co/contributor-agreement/
Happy coding!
Expand Down
25 changes: 25 additions & 0 deletions .github/workflows/code-format.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
name: Code style

on: [pull_request]

jobs:
build:

runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v2

- name: Use Node.js 14.x
uses: actions/setup-node@v1
with:
node-version: 14.x

- name: Install
run: |
npm install --prefix specification
- name: Code style check
run: |
npm run format:check --prefix specification
4 changes: 4 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ validation-api-response: ## Validate response of Endpoint with param: api=<api-
@echo ">> validating response of Endpoint: $(api)"
./run-validations.sh --api $(api) --response

format-code: ## Format the spec according to the style guide
@echo ">> validating formatting code"
@npm run format:fix --prefix specification

generate-spec: ## Generate the output spec
@echo ">> generating the spec .."
@npm run compile:canonical-json
Expand Down
141 changes: 0 additions & 141 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,147 +184,6 @@ Namespaced APIs can be validated in the same way, for example:
./run-validations.sh --api cat.health --request
```

## Custom types

The goal of the specification is to be used by different languages, from dynamically typed to statically typed.
To achieve this goal the specification contains a series of custom types that do not have a meaning
for the target language, but they should be translated to the most approriate construct.

The specification is written in [TypeScript](https://www.typescriptlang.org/), you can find all
the basic types [here](https://www.typescriptlang.org/docs/handbook/basic-types.html), while
in [`docs/special-classes.md`](./docs/special-classes.md) you can find custom classes for
defining set of APIs.

### Dictionary

Represents a dynamic key value map:

```ts
property: Dictionary<string, TypeDefinition>
```

For example:

```json
{
"property1": "type",
"property2": "other-type",
}
```

### SingleKeyDictionary

Represents a dynamic key value map with a single top level key:

```ts
property: SingleKeyDictionary<string, TypeDefinition>
```

For example:

```json
{
"onlyKey": "type"
}
```

### Array

Represents an array of the given value:

```ts
// generics syntax
property: Array<string>

// short syntax
property: string[]
```

### Union

Represents a type that can accept multiple types:

```ts
property: string | long
```

It can be combined with other types:
```ts
// array
property: Array<string | long>

// dictionary
property: Dictionary<string, string | long>
```

### Enum

Represents a set of allowed values:

```ts
enum MyEnum {
first = 0,
second = 1,
third = 2
}

property: MyEnum
```

### User defined value

Represents a value that will be defined by the user and has no specific type.

```ts
property: UserDefinedValue
```

### Numbers

The numeric type in TypeScript is `number`, but given that this specification target mutliple languages,
it offers a bunch of alias that represents the type that should be used if the language supports it:

```ts
type short = number
type byte = number
type integer = number
type long = number
type float = number
type double = number
```
### Strings
The string type in TypeScript is `string`. It's ok to use it in the spec, but to offer a more developer
friendly specification, we do offer a set of aliases based on which string we do expect, for example:
```ts
type ScrollId = string
type ScrollIds = string
type CategoryId = string
type ActionIds = string
type Field = string
type Id = string | number
type Ids = string | number | string[]
type IndexName = string
type Indices = string | string[]
...
```
You can find the full list [here](https://github.com/elastic/elastic-client-generator/blob/update-docs/specification/specs/common.ts),
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:
```ts
type Timestamp = string
type TimeSpan = string
interface Date {}
```

## FAQ

### A specific property is not always present, how do I define it?
Expand Down
43 changes: 43 additions & 0 deletions docs/behaviors.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Behaviors

Some APIs needs to be handled differenlty based on the output language, while others share many common parameters.
This document contains the list of this special interfaces and where those should be used.
Behaviors should be used via `implements` in the specification.

You can find all the special classes and aliases in in the [modeling guide](./modeling-guide.md).

## AdditionalProperties

In some places in the specification an object consists of the union of a set of known properties
and a set of runtime injected properties. Meaning that object should theoretically extend Dictionary but expose
a set of known keys and possibly. The object might already be part of an object graph and have a parent class.
This puts it into a bind that needs a client specific solution.
We therefore document the requirement to behave like a dictionary for unknown properties with this interface.

```ts
class IpRangeBucket implements AdditionalProperties<AggregateName, Aggregate> {}
```

## ArrayResponse

A response formatted as an array of records.
Some languages can't represent this easily and need to wrap the
array inside an object.

```ts
class CatAliasesResponse
extends ResponseBase
implements ArrayResponse<CatAliasesRecord> {}
```

## EmptyResponseBase

HEAD APIs can have a different behavior based on the language,
the response body is always empty to it's up to language generators
to define how those should be represented.

```ts
class DocumentExistsResponse
extends ResponseBase
implements EmptyResponseBase {}
```
140 changes: 140 additions & 0 deletions docs/modeling-guide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
# Modeling Guide

The goal of the specification is to be used by different languages, from dynamically typed to statically typed.
To achieve this goal the specification contains a series of custom types that do not have a meaning
for the target language, but they should be translated to the most approriate construct.

The specification is written in [TypeScript](https://www.typescriptlang.org/), you can find all
the basic types [here](https://www.typescriptlang.org/docs/handbook/basic-types.html),
while in [behaviors](./behaviors.md) you can find the list of special interfaces used
for describing APIs that can't be represented in the specification.

### Dictionary

Represents a dynamic key value map:

```ts
property: Dictionary<string, TypeDefinition>
```

For example:

```json
{
"property1": "type",
"property2": "other-type",
}
```

### SingleKeyDictionary

Represents a dynamic key value map with a single top level key:

```ts
property: SingleKeyDictionary<string, TypeDefinition>
```

For example:

```json
{
"onlyKey": "type"
}
```

### Array

Represents an array of the given value:

```ts
// generics syntax
property: Array<string>

// short syntax
property: string[]
```

### Union

Represents a type that can accept multiple types:

```ts
property: string | long
```

It can be combined with other types:
```ts
// array
property: Array<string | long>

// dictionary
property: Dictionary<string, string | long>
```

### Enum

Represents a set of allowed values:

```ts
enum MyEnum {
first = 0,
second = 1,
third = 2
}

property: MyEnum
```

### User defined value

Represents a value that will be defined by the user and has no specific type.

```ts
property: UserDefinedValue
```

### Numbers

The numeric type in TypeScript is `number`, but given that this specification target mutliple languages,
it offers a bunch of alias that represents the type that should be used if the language supports it:

```ts
type short = number
type byte = number
type integer = number
type long = number
type float = number
type double = number
```
### Strings
The string type in TypeScript is `string`. It's ok to use it in the spec, but to offer a more developer
friendly specification, we do offer a set of aliases based on which string we do expect, for example:
```ts
type ScrollId = string
type ScrollIds = string
type CategoryId = string
type ActionIds = string
type Field = string
type Id = string | number
type Ids = string | number | string[]
type IndexName = string
type Indices = string | string[]
...
```
You can find the full list [here](https://github.com/elastic/elastic-client-generator/blob/update-docs/specification/specs/common.ts),
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:
```ts
type Timestamp = string
type TimeSpan = string
interface Date {}
```
Loading

0 comments on commit 96062d3

Please sign in to comment.