Shell Scripts

Shell scripts are an easy way of executing a piece of code from the command line. They can be used in a variety of scenarios and can be a simple code snippet or be more complex and call application services.

Structure

A shell script file is divided into two parts: a main function, which contains the code to be executed, and a schema, which parses and validates the arguments given on the command line and passes them on to the main function. The file must be located in the src/scripts directory.

Example: src/scripts/create-user.ts

// 3p
import { ServiceManager } from '@foal/core';

// App
import { dataSource } from '../db';
import { User } from '../app/entities';

export const schema = {
  type: 'object',
  properties: {
    email: { type: 'string' },
  },
  required: ['email'],
  additionalProperties: false
}

export async function main(args: { email: string }) {
  await dataSource.initialize();

  try {
    const user = new User();
    user.email = args.email;

    await user.save();
  } finally {
    dataSource.destroy();
  }
}

Generating, Building and Running Shell Scripts

To generate a new script, you can use the CLI generate command:

npx foal generate script create-user
# or
npx foal g script create-user

If you need to build the script once, run this command:

npm run build

If you need to build and watch it in dev mode, use this command:

npm run dev

Then you can run the script as follows:

npx foal run create-user email=foo@foalts.org

Accessing Services

If you wish to access a service, you can use the ServiceManager instance passed as second argument to the main function.

Example

import { ServiceManager } from '@foal/core';

import { MyService } from '../app/services';

export function main(args: any, services: ServiceManager) {
  const myService = services.get(MyService);

  // Do something with myService.
}

Logging

When a script is executed, the script name as well as a script ID are added to the log context. Like the request ID in an HTTP request, the script ID is added as a parameter to every log printed during script execution, including any errors. In this way, it is possible to aggregate all logs from a single script execution in a logging program.

If you wish to access the logger in the script, it is passed as the third argument to the main function.

import { Logger, ServiceManager } from '@foal/core';


export function main(args: any, services: ServiceManager, logger: Logger) {
  logger.info('Hello world!');
}