@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 cli, trv is a compilation aware entry point, that 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, always builds the entire project. With the efficient caching behavior, this leads to generally a minimal overhead but allows for centralization of all operations.

The CLI supports the following operations:

• clean - Removes the output folder, and if -a is also passed, will also clean out the compiler folder
• build - Will attempt to build the project. If the project is already built, will return immediately. If the project is being built somewhere else, will wait until a build is completed.
• watch - If nothing else is watching, will start the watch operation. Otherwise will return immediately.
• manifest - Will produce a manifest. If no file is passed in the command line arguments, will output to stdout.
• <other> - Will be delegated to the Command Line Interface entry point after a successful build. 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 trv build

2029-03-14T04:00:00.618Z [lock           ] Acquiring build
2029-03-14T04:00:00.837Z [precompile     ] Started
2029-03-14T04:00:01.510Z [precompile     ] @travetto/terminal Skipped
2029-03-14T04:00:02.450Z [precompile     ] @travetto/manifest Skipped
2029-03-14T04:00:02.762Z [precompile     ] @travetto/transformer Skipped
2029-03-14T04:00:02.947Z [precompile     ] @travetto/compiler Skipped
2029-03-14T04:00:03.093Z [precompile     ] Completed
2029-03-14T04:00:04.003Z [manifest       ] Started
2029-03-14T04:00:04.495Z [manifest       ] Completed
2029-03-14T04:00:05.066Z [transformers   ] Started
2029-03-14T04:00:05.307Z [transformers   ] @travetto/base Skipped
2029-03-14T04:00:05.952Z [transformers   ] @travetto/cli Skipped
2029-03-14T04:00:06.859Z [transformers   ] @travetto/manifest Skipped
2029-03-14T04:00:07.720Z [transformers   ] @travetto/registry Skipped
2029-03-14T04:00:08.179Z [transformers   ] @travetto/schema Skipped
2029-03-14T04:00:08.588Z [transformers   ] Completed
2029-03-14T04:00:09.493Z [delta          ] Started
2029-03-14T04:00:10.395Z [delta          ] Completed
2029-03-14T04:00:10.407Z [manifest       ] Started
2029-03-14T04:00:10.799Z [manifest       ] Wrote manifest @travetto-doc/compiler
2029-03-14T04:00:11.013Z [manifest       ] Completed
2029-03-14T04:00:11.827Z [compile        ] Started action=build changed=
2029-03-14T04:00:11.894Z [compile        ] Skipped
2029-03-14T04:00:12.133Z [lock           ] Releasing build
2029-03-14T04:00:13.123Z [build          ] Successfully built

Terminal: Sample trv output with default log level

$ trv 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
• Lock Management - Manages cross-process interaction to ensure single compiler
• 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 trv entrypoint, along with a small context utility in Manifest are the only Javascript files needed to run the project. The trv 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.

Lock Management

The compiler supports invocation from multiple locations at the same time, and provides a layer of orchestration to ensure a single process is building at a time. For a given project, there are four main states:

• No Watch - Building
• Watch - No Build
• Watch - Building
• Inactive / Stale Depending on what state the project is in (depending on various processes), will influence what the supporting tooling should do. LockManager represents the majority of the logic for tracking various states, and informing what action should happen when in the above states.