Nestjs Command

Description

Nest.js Command tools, based on yargs.

Dependency

• Use version 3.* for nestjs 6.*, 7.*, 8.*, 9.*, 10.*, 11.*, yargs 16.*, 17.*
• Use version 2.* for nestjs 6.*, 7.*, 8.*, yargs 11.*, 12.*, 13.*, 14.*, 15.*
• Use version 1.* for nestjs 6.*, 7.*
• Use version 0.* for nestjs 5.*

BREAKING CHANGES (3.*)

In version 3.* has changes:

• Drop: autoExit
• Drop: CommandService.isRunning
• Drop: CommandLogService
• New: CommandService.exec() return Promise (Support async/await)
• yargs only support 15.1.*, 16.*, 17.*

Installation

1$ npm install --save nestjs-command yargs
2
3# if you use typescript
4$ npm install --save-dev @types/yargs

Quick Start

Register the command module in your base module: ./src/app.module.ts

1import { Module } from '@nestjs/common';
2import { CommandModule } from 'nestjs-command';
3
4@Module({
5  imports: [CommandModule]
6})
7export class AppModule {}

Create a Cli entrypoint: ./src/cli.ts

1import { NestFactory } from '@nestjs/core';
2import { CommandModule, CommandService } from 'nestjs-command';
3import { AppModule } from './app.module';
4
5async function bootstrap () {
6  const app = await NestFactory.createApplicationContext(AppModule, {
7    logger: false
8  });
9
10  try {
11    await app
12      .select(CommandModule)
13      .get(CommandService)
14      .exec();
15    await app.close()
16  } catch (error) {
17    console.error(error);
18    await app.close();
19    process.exit(1);
20  }
21}
22
23bootstrap();

And create your command providers (see the example below).

Run your program in either ways:

• npx nestjs-command: run by default ./src/cli.ts
• CLI_PATH=./dist/cli.js npx nestjs-command: run /dist/cli.js with the CLI_PATH env

Notice

Make sure to set CLI_ENV=./dist/cli.js when using commands in production with pre-compiled typescript

Usage example

Note: you will find documentation about yargs command positional here, and yargs command options here.

Create a simple Command File: ./src/user/user.command.ts

1import { Command, Positional, Option } from 'nestjs-command';
2import { Injectable } from '@nestjs/common';
3import { UserService } from './user.service';
4
5@Injectable()
6export class UserCommand {
7  constructor(private readonly userService: UserService) {}
8
9  @Command({
10    command: 'create:user <username>',
11    describe: 'create a user',
12  })
13  async create(
14    @Positional({
15      name: 'username',
16      describe: 'the username',
17      type: 'string'
18    })
19    username: string,
20    @Option({
21      name: 'group',
22      describe: 'user group (ex: "jedi")',
23      type: 'string',
24      alias: 'g',
25      required: false
26    })
27    group: string,
28    @Option({
29      name: 'saber',
30      describe: 'if user has a lightsaber',
31      type: 'boolean',
32      default: false,
33      required: false
34    })
35    saber: boolean
36  ) {
37    this.userService.add({
38      username,
39      group,
40      saber
41    });
42  }
43}

Create a simple Service File: ./src/user/user.service.ts

1import { Injectable } from '@nestjs/common';
2
3@Injectable()
4export class UserService {
5  async add(user: any): Promise<any> {
6    return Promise.resolve().then(() => {
7      console.log('user added:', user);
8    });
9  }
10}

Register this UserCommand and UserService as providers in your base module: ./src/app.module.ts

1import { Module } from '@nestjs/common';
2import { CommandModule } from 'nestjs-command';
3import { UserCommand } from './user/user.command';
4import { UserService } from './user/user.service';
5
6@Module({
7  imports: [CommandModule],
8  providers: [UserCommand, UserService]
9})
10export class AppModule {}

And create a cli entrypoint: ./src/cli.ts

1import { NestFactory } from '@nestjs/core';
2import { CommandModule, CommandService } from 'nestjs-command';
3import { AppModule } from './app.module';
4
5async function bootstrap() {
6  const app = await NestFactory.createApplicationContext(AppModule, {
7    logger: ['error'] // only errors
8  });
9
10  try {
11    await app
12      .select(CommandModule)
13      .get(CommandService)
14      .exec();
15    await app.close()
16  } catch (error) {
17    console.error(error);
18    await app.close();
19    process.exit(1);
20  }
21}
22bootstrap();

Run your program in a terminal

Get some help:

1$ npx nestjs-command create:user --help
2cli create:user <username>
3
4create a user
5
6Positionals:
7  username  the username                                     [string] [required]
8
9Options:
10  -h, --help     Show help                                             [boolean]
11  --saber        if user has a lightsaber             [boolean] [default: false]
12  --group, -g    user group (ex: "jedi")                                [string]
13  -v, --version  Show version number                                   [boolean]

Add a new user:

1$ npx nestjs-command create:user anakin --group jedi --no-saber
2user added: { username: 'anakin', group: 'jedi', saber: false }
3
4$ npx nestjs-command create:user yoda --group jedi --saber
5user added: { username: 'yoda', group: 'jedi', saber: true }

How to test it?

1import { Test } from '@nestjs/testing';
2import { CommandModule, CommandModuleTest } from 'nestjs-command';
3import { AppModule } from './app.module';
4
5describe('AppModule', () => {
6  let commandModule: CommandModuleTest;
7
8  beforeEach(async () => {
9    const moduleFixture = await Test.createTestingModule({
10      imports: [AppModule]
11    }).compile();
12
13    const app = moduleFixture.createNestApplication();
14    await app.init();
15    commandModule = new CommandModuleTest(app.select(CommandModule));
16  });
17
18  it('test command module', async () => {
19    const command = 'create:user <username>';
20    const args = { username: 'Foo', group: 'Bar', saber: false };
21
22    const user = await commandModule.execute(command, args);
23    expect(user.username).toBe('Foo')
24    expect(user.group).toBe('Bar')
25  });
26});