# TypeScript

Elements is the first build tool to compile the TypeScript compiler, the Go
implementation, directly into its own binary. Type checking is a phase of the
build, running in the same process against the same in-memory source graph as
compilation, so a save is checked, compiled, and hot reloaded in a few
milliseconds. Both targets are checked, the browser and the server, each
against the types it actually has.

## One program, one graph

Every source in a project has a version derived from its content and the
versions of everything it imports. The checker consults that version like every
other phase of the build: a file whose version has not moved is not rechecked,
and a change deep in the graph rechecks exactly the cone that depends on it.
The same graph drives the build cache, the test runner, hot reload, and the
deploy, so type checking, compilation, and release agree on one version of
every file.

Checking runs incrementally inside the build loop, on the same thread that
watches your files. A single-file save typically type checks, compiles, and hot
reloads in a few milliseconds.

## The Elements languages are TypeScript

Elements HTML templates and JSOC config files are implemented on top of the
TypeScript compiler's own binder, symbol table, and checker, not beside them. A
template attribute is a TypeScript declaration. A template name resolves
through the normal symbol table. The expressions inside `{}` are checked
against the surrounding scope by the same checker that checks a `.ts` file,
with the same error messages. There is no second type system to learn, and no
seam where TypeScript ends and Elements begins.

```html
<Comment (comment: Comment, private editing: boolean = false)>
  <p>{comment.text.toUpperCase()}</p>
  <p>{comment.txet}</p>   <!-- error: Property 'txet' does not exist on type 'Comment' -->
</Comment>
```

## Two targets, one source

A file is checked for every target it reaches. Server code sees Node's types
and the server half of `@elements/app`; browser-reachable code sees the DOM and
the browser half. A server-only call such as `sql()` made from code the browser
can reach is a compile error at the call site, so a query or a secret cannot
reach the browser by accident. You do not annotate anything; the compiler
follows the call graph. See `rpc` for the boundary and `async` for how
sync-style calls type check without `await`.

## Options

TypeScript options live under `build.typescript` in `config.jsoc`, a flat
mirror of tsconfig's `compilerOptions` limited to the options Elements honors.
Strict checking is on. There is no `tsconfig.json` in an Elements project and
you should not add one.

```jsoc
build: {
  typescript: {
    lib: ["es2022", "dom"],
  },
},
```

Full config syntax: `config`.

## Editors

The project server speaks the Language Server Protocol, so editors get
completions, diagnostics, go-to-definition, and rename for `.ts` files, HTML
templates, and JSOC alike, from the same checker the build uses. It replaces
`tsserver`. VS Code and its derivatives get this automatically; the extension
is installed when you install Elements. For vim and neovim see `vim`.

## Diagnostics

Type errors are build errors. They appear in `elements build`, in
`elements build -json` as diagnostics with a `path` and a 1-based `loc`, and in
the editor, all from one check. A build with a type error anywhere does not
release, and neither do the tests it would have gated. See `build`.

## Related

- `build`: the loop the checker runs inside.
- `html`: the template language the checker understands.
- `config`: `build.typescript`.
- `async`: the sync-style transform and how it types.