# Runtime errors

There are several runtime errors that Gleam code can throw. This documentation
lists them and their runtime properties.

On Erlang runtime errors are Erlang maps thrown with `erlang:error/1`, having at
least these properties:

| Key         | Type   | Value                                       |
| ---         | ----   | -----                                       |
| gleam_error | Atom   | See individual errors                       |
| message     | String | See individual errors                       |
| file        | String | A path to the original source file location |
| module      | String | The module the error occurred in            |
| function    | String | The function the error occurred in          |
| line        | Int    | The line number the error occurred on       |

On JavaScript runtime errors are instances of the JavaScript `Error` class,
having at least these properties added to them:

| Key         | Type   | Value                                 |
| ---         | ----   | -----                                 |
| gleam_error | String | See individual errors                 |
| message     | String | See individual errors                 |
| module      | String | The module the error occurred in      |
| function    | String | The function the error occurred in    |
| line        | Number | The line number the error occurred on |

## Todo

A panic that indicates that the code has not yet been completed, intended for
use in development.

```gleam
todo
todo as "some message"
```
| Key         | Erlang Value      | JavaScript Value  |
| ---         | ------------      | ----------------  |
| gleam_error | `todo`            | `"todo"`          |
| message     | The given message | The given message |

## Panic

An explicit panic to unconditionally error.

```gleam
panic
panic as "some message"
```
| Key         | Erlang Value      | JavaScript Value  |
| ---         | ------------      | ----------------  |
| gleam_error | `panic`           | `"panic"`         |
| message     | The given message | The given message |

## Let assert

An inexhaustive pattern match, erroring if the pattern does not match.

```gleam
let assert Ok(x) = something()
let assert Error(e) = something() as "This should fail"
```
| Key                  | Erlang Value                                               | JavaScript Value                                          |
| ---                  | ------------                                               | ----------------                                          |
| gleam_error          | `let_assert`                                               | `"let_assert"`                                            |
| message              | The given message                                          | The given message                                         |
| value                | The unmatched value                                        | The unmatched value                                       |
| start                | The byte-index of the start of the `let assert` statement  | The byte-index of the start of the `let assert` statement |
| end                  | The byte-index of the end of the `let assert` statement    | The byte-index of the end of the `let assert` statement   |
| pattern_start        | The byte-index of the start of the asserted pattern        | The byte-index of the start of the asserted pattern       |
| pattern_end          | The byte-index of the end of the asserted pattern          | The byte-index of the end of the asserted pattern         |

## Assert

An assertion of a boolean value.

The error format of `assert` differs based on the expression that is asserted.
It always has these fields:

| Key              | Erlang Value                                           | JavaScript Value                                       |
| ---              | ------------                                           | ----------------                                       |
| gleam_error      | `assert`                                               | `"assert"`                                             |
| message          | The given message                                      | The given message                                      |
| kind             | The kind of asserted expression                        | The kind of asserted expression                        |
| start            | The byte-index of the start of the `assert` statement  | The byte-index of the start of the `assert` statement  |
| end              | The byte-index of the end of the `assert` expression   | The byte-index of the end of the `assert` expression   |
| expression_start | The byte-index of the start of the asserted expression | The byte-index of the start of the asserted expression |

But, depending on the expression that was asserted, it contains additional
information which can be used to diagnose the error.

### Binary operators

```gleam
assert level >= 30
```

| Key       | Erlang Type  | JavaScript Type  | Value                              |
| ---       | -----------  | ---------------  | -----                              |
| kind      | Atom         | String           | `binary_operator`                  |
| operator  | Atom         | String           | The binary operator that was used  |
| left      | Map          | Object           | The left hand side of the operator |
| right     | Map          | Object           | The left hand side of the operator |

### Function calls

```gleam
assert check_some_property(a, b, c)
```

| Key       | Erlang Type  | JavaScript Type  | Value                                  |
| ---       | -----------  | ---------------  | -----                                  |
| kind      | Atom         | String           | `function_call`                        |
| arguments | List of map  | Array of objects | The arguments of the asserted function |

### Other expressions

```gleam
assert other_expression
```

| Key        | Erlang Type  | JavaScript Type  | Value                                |
| ---        | -----------  | ---------------  | -----                                |
| kind       | Atom         | String           | `expression`                         |
| expression | Map          | Object           | The value of the asserted expression |

The expression maps have this structure:

| Key    | Erlang Type  | JavaScript Type  | Value                                                             |
| ---    | -----------  | ---------------  | -----                                                             |
| value  | any          | any              | the value the expression evaluated to at runtime                  |
| kind   | Atom         | String           | `literal` or `expression` or `unevaluated`                        |
| start  | Int          | Number           | The byte-index of the start of this expression in the source code |
| end    | Int          | Number           | The byte-index of the end of this expression in the source code   |

If the expression is a literal, such as `True` or `15`, it will have the `literal`
kind. This signals that its value is not runtime dependent, and may not need to
be printed.

If the expression is on the right hand side of a short-circuiting operator, like
`||` or `&&`, it might not be evaluated. If the operator short-circuits, the right
hand side expression will have kind `unevaluated`.