@travetto/app

Application

Application registration/management and run support.

Install: @travetto/app

npm install @travetto/app

# or

yarn add @travetto/app

The Base module provides a simplistic entrypoint to allow for the application to run, but that is not sufficient for more complex applications. This module provides a decorator, @Application who's job is to register entry points into the application, along with the associated metadata.

With the application, the run method is the entry point that will be invoked post construction of the class. Building off of the Dependency Injection, the @Application is a synonym for @Injectable, and inherits all the abilities of dependency injection. This should allow for setup for any specific application that needs to be run.

For example:

Code: Example of Application target

import { Injectable, Inject } from '@travetto/di';
import { Application } from '@travetto/app';

@Injectable()
class Server {
  name = 'roger';

  async launch() {
    // ...
  }
}

@Application('simple-app')
class SimpleApp {

  @Inject()
  server: Server;

  async run() {
    return this.server.launch();
  }
}

Additionally, the @Application decorator exposes some additional functionality, which can be used to launch the application.

run() Arguments

The arguments specified in the run method are extracted via code transformation, and are able to be bound when invoking the application. Whether from the command line or a plugin, the parameters will be mapped to the inputs of run. For instance:

Code: Simple Entry Point with Parameters

import { Application } from '@travetto/app';

@Application('simple-domain')
class SimpleApp {
  async run(domain: string, port = 3000) {
    console.log('Launching', { domain, port });
  }
}

CLI - run

The run command allows for invocation of applications as defined by the @Application decorator. Additionally, the environment can manually be specified (dev, test, prod).

Terminal: CLI Run Help

$ trv run --help

Usage:  run [options] <application> [args...]

Options:
  -e, --env <env>          Application environment
  -p, --profile <profile>  Additional application profiles (default: [])
  -h, --help               display help for command

Available Applications:

   ● complex 
     usage:  complex domain:string [port:number=3000]
     target: @travetto/app:doc/complex￮Complex

     ——————————————————————————————————————————————————————————

   ● simple 
     usage:  simple domain:string [port:number=3000]
     target: @travetto/app:doc/simple￮SimpleApp

     ——————————————————————————————————————————————————————————

   ● simple-app 
     usage:  simple-app 
     target: @travetto/app:doc/entry-simple￮SimpleApp

     ——————————————————————————————————————————————————————————

   ● simple-domain 
     usage:  simple-domain domain:string [port:number=3000]
     target: @travetto/app:doc/domain￮SimpleApp

     ——————————————————————————————————————————————————————————

   ● test-ep-test 
     usage:  test-ep-test [age:number=5] [format:html|pdf=html]
     target: @travetto/app:doc/entry￮EpTest

Running without specifying an application trv run, will display all the available apps, and would look like:

Terminal: Sample CLI Output

$ trv run

Usage: trv run [options] <application> [args...]

Options:
  -e, --env <env>          Application environment
  -p, --profile <profile>  Additional application profiles (default: [])
  -h, --help               display help for command

Available Applications:

   ● complex 
     usage:  complex domain:string [port:number=3000]
     target: @travetto/app:doc/complex￮Complex

     ——————————————————————————————————————————————————————————

   ● simple 
     usage:  simple domain:string [port:number=3000]
     target: @travetto/app:doc/simple￮SimpleApp

     ——————————————————————————————————————————————————————————

   ● simple-app 
     usage:  simple-app 
     target: @travetto/app:doc/entry-simple￮SimpleApp

     ——————————————————————————————————————————————————————————

   ● simple-domain 
     usage:  simple-domain domain:string [port:number=3000]
     target: @travetto/app:doc/domain￮SimpleApp

     ——————————————————————————————————————————————————————————

   ● test-ep-test 
     usage:  test-ep-test [age:number=5] [format:html|pdf=html]
     target: @travetto/app:doc/entry￮EpTest

To invoke the simple application, you need to pass domain where port is optional with a default.

Terminal: Invoke Simple

$ trv run simple-domain my-domain.biz 4000

Running application { name: 'simple-domain', target: '@travetto/app:doc/domain￮SimpleApp' }
Manifest {
  info: {
    name: '@travetto-doc/app',
    main: undefined,
    author: undefined,
    license: undefined,
    version: '0.0.0',
    framework: '3.0.x'
  },
  env: {
    envName: 'dev',
    debug: '0',
    prod: false,
    test: false,
    dynamic: false,
    profiles: [ 'dev' ],
    resourcePaths: [],
    nodeVersion: 'v18.x.x'
  }
}
Config { sources: [ 'override.3 - memory://override' ], active: {} }
Launching { domain: 'my-domain.biz', port: 4000 }

Type Checking

The parameters to run will be type checked, to ensure proper evaluation.

Terminal: Invoke Simple with bad port

$ trv run simple-domain my-domain.biz orange

Failed to run simple-domain, Validation errors have occurred
● port is not a valid number

The types are inferred from the .run() method parameters, but can be overridden in the @Application annotation to support customization. Only primitive types are supported:

• number - Float or decimal
• string - Default if no type is specified
• boolean - true(yes/on/1) and false(no/off/0)
• union - Type unions of the same type (string_a | string_b or 1 | 2 | 3 | 4) Customizing the types is done by name, and allows for greater control:

Code: Complex Entry Point with Customization

import { Application } from '@travetto/app';

@Application('complex')
class Complex {
  async run(domain: string, port: number = 3000) {
    console.log('Launching', { domain, port });
  }
}