esdl 0.6.0

Event-sourcing Schema Definition Language parser
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

# ESDL

**E**vent-sourcing **S**chema **D**efinition **L**anguage

---

Schema definition language for defining aggregates, commands, events & custom types.

Heavily inspired by GraphQL syntax, you can describe aggregates which can be used for codegen in different languages.

## Install

> Due to the wit-bindgen project not having their crates published yet (see https://github.com/bytecodealliance/wit-bindgen/issues/180),
> `esdl` is not up to date on crates.io and it's advised to use the git url as the dependency for now.

```toml
esdl = { git = "https://github.com/thalo-rs/esdl", features = ["codegen-rust"] }
```

_Possible features include `codegen-rust`, `codegen-rust-wasm` and `codegen-typescript`._

## Code generation

ESDL schemas can be used for code generation.

The [Rust crate](https://crates.io/crates/esdl) currently supports code generation for:

- [Rust](https://docs.rs/esdl/latest/esdl/codegen/rust/struct.RustCompiler.html) (`codegen-rust`)
- [Rust WASM](https://docs.rs/esdl/latest/esdl/codegen/rust/wasm/struct.RustWasmCompiler.html) (`codegen-rust-wasm`)
- [TypeScript](https://docs.rs/esdl/latest/esdl/codegen/typescript/struct.TypeScriptCompiler.html) (`codegen-typescript`)

Additional languages may be added in the future. Contributions are welcome!

## Example

```
version = "0.1.0"

aggregate BankAccount {
  open_account(initial_balance: Float) -> OpenedAccount
  deposit_funds(amount: Float) -> ReceivedFunds
  withdraw_funds(amount: Float) -> SentFunds
  send_funds(amount: Float, user: User) -> (SentFunds? | ReceivedFunds?)
}

event OpenedAccount {
  initial_balance: Float
}

event SentFunds {
  amount: Float
  user: User?
}

event ReceivedFunds {
  amount: Float
  user: User?
}

type User {
  id: String
  name: String?
}
```

### Scalar Types

| Scalar   | Rust Type   | TypeScript Type |
| -------- | ----------- | --------------- |
| `String` | [`String`]  | [`string`][ts]  |
| `Int`    | [`i32`]     | [`number`][ts]  |
| `Long`   | [`i64`]     | [`number`][ts]  |
| `Float`  | [`f32`]     | [`number`][ts]  |
| `Double` | [`f64`]     | [`number`][ts]  |
| `Bool`   | [`bool`]    | [`boolean`][ts] |
| `Bytes`  | [`Vec<u8>`] | [`string`][ts]  |

[`string`]: https://doc.rust-lang.org/stable/std/string/struct.String.html
[`i32`]: https://doc.rust-lang.org/stable/std/primitive.i32.html
[`i64`]: https://doc.rust-lang.org/stable/std/primitive.i64.html
[`f32`]: https://doc.rust-lang.org/stable/std/primitive.f32.html
[`f64`]: https://doc.rust-lang.org/stable/std/primitive.f64.html
[`bool`]: https://doc.rust-lang.org/stable/std/primitive.bool.html
[`vec<u8>`]: https://doc.rust-lang.org/stable/std/vec/struct.Vec.html
[ts]: https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#the-primitives-string-number-and-boolean

### Optional & Required

Types can be marked as optional by adding the `?` suffix.

| Type     | Syntax | Example   |
| -------- | ------ | --------- |
| Required | `T`    | `String`  |
| Optional | `T?`   | `String?` |

### Repeating Types

Types can be repeated by wrapping them in `[]`.

| Type   | Syntax | Example    |
| ------ | ------ | ---------- |
| Single | `T`    | `String`   |
| Array  | `[T]`  | `[String]` |

Remember, we can mark types as optional, even in arrays.

| Type                 | Syntax  | Example      |
| -------------------- | ------- | ------------ |
| Optional Array       | `[T?]?` | `[String?]?` |
| Required Array       | `[T?]`  | `[String?]`  |
| Required Array Items | `[T]?`  | `[String]?`  |
| Required Array Items | `[T]`   | `[String]`   |

---

Integrates with [Thalo](https://github.com/thalo-rs/thalo) to generate Rust code.