@travetto/compiler

Compiler

The compiler infrastructure for the Travetto framework

Install: @travetto/compiler

npm install @travetto/compiler

# or

yarn add @travetto/compiler

This module expands upon the Typescript compiler, with the additional features:

• Integration with the Transformation module, allowing for rich, type-aware transformations
• Automatic conversion to either Ecmascript Module or CommonJS based on the Package JSON type value
• Removal of type only imports which can break Ecmascript Module-style output
• Automatic addition of .js extension to imports to also support Ecmascript Module-style output Beyond the Typescript compiler functionality, the module provides the primary entry point into the development process.

CLI

The compiler cli, trvc 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|watch - 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 --prod [output] - Generate the 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

$ 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 [main           ] Start Server
2029-03-14T04:00:01.510Z debug [event-stream   ] Started event stream
2029-03-14T04:00:02.450Z debug [precompile     ] Started
2029-03-14T04:00:02.762Z debug [precompile     ] Skipped @travetto/manifest
2029-03-14T04:00:02.947Z debug [precompile     ] Skipped @travetto/transformer
2029-03-14T04:00:03.093Z debug [precompile     ] Skipped @travetto/compiler
2029-03-14T04:00:04.003Z debug [precompile     ] Completed
2029-03-14T04:00:04.495Z debug [manifest       ] Started
2029-03-14T04:00:05.066Z debug [manifest       ] Completed
2029-03-14T04:00:05.307Z debug [transformers   ] Started
2029-03-14T04:00:05.952Z debug [transformers   ] Skipped @travetto/cli
2029-03-14T04:00:06.859Z debug [transformers   ] Skipped @travetto/runtime
2029-03-14T04:00:07.720Z debug [transformers   ] Skipped @travetto/schema
2029-03-14T04:00:08.179Z debug [transformers   ] Completed
2029-03-14T04:00:08.588Z debug [delta          ] Started
2029-03-14T04:00:09.493Z debug [delta          ] Completed
2029-03-14T04:00:10.395Z debug [manifest       ] Started
2029-03-14T04:00:10.407Z debug [manifest       ] Wrote manifest @travetto-doc/compiler
2029-03-14T04:00:10.799Z debug [manifest       ] Completed
2029-03-14T04:00:11.013Z info  [server         ] State changed: compile-end
2029-03-14T04:00:11.827Z debug [compiler-exec  ] Skipped
2029-03-14T04:00:11.894Z debug [event-stream   ] Finished event stream
2029-03-14T04:00:12.133Z info  [server         ] Closing down server
2029-03-14T04:00:13.123Z debug [server         ] Server close event
2029-03-14T04:00:14.014Z info  [server         ] Closed down server
2029-03-14T04:00:14.924Z debug [server         ] Finished processing events
2029-03-14T04:00:15.690Z debug [main           ] End Server

Terminal: Sample trv output with default log level

$ trvc build

Compilation Architecture

The compiler will move through the following phases on a given compilation execution:

• Bootstrapping - Initial compilation of Compiler's support/*.ts files
• Compiler Server - Provides a simple HTTP interface to watching compiler file and state changes, and synchronizing multiple processes
• Build Compiler - Leverages Typescript to build files needed to execute compiler
• Build Manifest - Produces the manifest for the given execution
• Build Transformers - Leverages Typescript 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 compiler with the aforementioned enhancements

Bootstrapping

Given that the framework is distributed as Typescript only files, there is a bootstrapping problem that needs to be mitigated. The trvc entrypoint, along with a small context utility in Manifest are the only Javascript files needed to run the project. The trvc entry point will compile @travetto/compiler/support/* files as the set that is used at startup. These files are also accessible to the compiler as they get re-compiled after the fact.