<!-- This file was generated by @travetto/doc and should not be modified directly -->
<!-- Please modify https://github.com/travetto/travetto/tree/main/module/compiler/DOC.tsx and execute "npx trv doc" to rebuild -->
# Compiler

## The compiler infrastructure for the Travetto framework

**Install: @travetto/compiler**
```bash
npm install @travetto/compiler

# or

yarn add @travetto/compiler
```

This module expands upon the [Typescript](https://typescriptlang.org) compiler, with the additional features:
   *  Integration with the [Transformation](https://github.com/travetto/travetto/tree/main/module/transformer#readme "Functionality for AST transformations, with transformer registration, and general utils") module, allowing for rich, type-aware transformations
   *  Automatic conversion to either [Ecmascript Module](https://nodejs.org/api/esm.html) or [CommonJS](https://nodejs.org/api/modules.html) based on the [Package JSON](https://docs.npmjs.com/cli/v9/configuring-npm/package-json) `type` value
   *  Removal of type only imports which can break [Ecmascript Module](https://nodejs.org/api/esm.html)-style output
   *  Automatic addition of `.js` extension to imports to also support [Ecmascript Module](https://nodejs.org/api/esm.html)-style output

Beyond the [Typescript](https://typescriptlang.org) compiler functionality, the module provides the primary entry point into the development process.

## CLI
The compiler cli, [trvc](https://github.com/travetto/travetto/tree/main/module/compiler/bin/trvc.js) is the entry point for compilation-related operations. It has the ability to check for active builds, and ongoing watch operations to ensure only one process is building at a time. Within the framework, regardless of mono-repo or not, the compilation always targets the entire project. With the efficient caching behavior, this leads to generally a minimal overhead but allows for centralization of all operations. 

The compiler cli supports the following operations:
   *  `start` - Run the compiler in watch mode
   *  `stop` - Stop the compiler if running
   *  `restart` - Restart the compiler in watch mode
   *  `build` - Ensure the project is built and upto date
   *  `clean` - Clean out the output and compiler caches
   *  `info` - Retrieve the compiler information, if running
   *  `event <log|progress|state>` - Watch events in realtime as newline delimited JSON
   *  `exec <file> [...args]` - Allow for compiling and executing an entrypoint file
   *  `manifest [output]` - Generate the project manifest
   *  `manifest:production [output]` - Generate the production project manifest

In addition to the normal output, the compiler supports an environment variable `TRV_BUILD` that supports the following values: `debug`, `info`, `warn` or `none`. This provides different level of logging during the build process which is helpful to diagnose any odd behaviors. When invoking an unknown command (e.g. `<other>` from above), the default level is `warn`. Otherwise the default logging level is `info`.

**Terminal: Sample trv output with debug logging**
```bash
$ TRV_BUILD=debug trvc build

2029-03-14T04:00:00.618Z info  [server         ] Starting server http://127.0.0.1:25539
2029-03-14T04:00:00.837Z debug [compiler-exec  ] Start Server
2029-03-14T04:00:01.510Z debug [event-stream   ] Started event stream
2029-03-14T04:00:02.450Z info  [compiler-exec  ] Launching compiler
2029-03-14T04:00:02.762Z debug [server         ] Compilation started
2029-03-14T04:00:02.947Z info  [server         ] State changed: init
2029-03-14T04:00:03.093Z debug [server         ] Compiler loaded: 0 files changed
2029-03-14T04:00:04.003Z info  [server         ] State changed: compile-start
2029-03-14T04:00:04.495Z info  [server         ] State changed: compile-end
2029-03-14T04:00:05.066Z debug [server         ] Compiler process shutdown
2029-03-14T04:00:05.307Z debug [compiler-exec  ] Finished
2029-03-14T04:00:05.952Z debug [event-stream   ] Finished event stream
2029-03-14T04:00:06.859Z debug [compiler-exec  ] Shutting down process
2029-03-14T04:00:07.720Z info  [server         ] Closing down server
2029-03-14T04:00:08.179Z debug [server         ] Server close event
2029-03-14T04:00:08.588Z info  [server         ] Closed down server
2029-03-14T04:00:09.493Z debug [server         ] Finished processing events
2029-03-14T04:00:10.395Z debug [compiler-exec  ] End Server
```

**Terminal: Sample trv output with default log level**
```bash
$ trvc build
```

## Compilation Architecture
The compiler will move through the following phases on a given compilation execution:
   *  `Compiler Server` - Provides a simple HTTP interface to watching compiler file and state changes, and synchronizing multiple processes
   *  `Build Compiler` - Leverages [Typescript](https://typescriptlang.org) to build files needed to execute compiler
   *  `Build Manifest` - Produces the manifest for the given execution
   *  `Build Transformers` - Leverages [Typescript](https://typescriptlang.org) to compile all transformers defined in the manifest
   *  `Produce Manifest Delta` - Compare the output file system with the manifest to determine what needs to be compiled
   *  `Clear all output if needed` - When the compiler source or transformers change, invalidate the entire output
   *  `Persist Manifest(s)` - Ensure the manifest is available for the compiler to leverage. Multiple will be written if in a monorepo
   *  `Invoke Compiler` - Run [Typescript](https://typescriptlang.org) compiler with the aforementioned enhancements