@typesys/console

CONSOLE

Console generate workspace to implement Command Line Interface (CLI) application. Generated workspace is using Typescript as programming language to build the CLI application.

By default generated workspace based on native ESM module system. Developer can change it to CommonJS if required.

Need to have understanding of node.js supports for CLI as content of the generated scripts in the workspace are used api provided by node.js for CLI.

• Benefits
• Installation
• Usage
  • CLI
  • API
• Commands
• Workspace
  • Structure
  • Architecture/Design
  • Build
  • Run
  • Add new command

Benefits

• Access command in CLI & API form.
• Centralized error handling system.
• Easily add/remove commands.
• Robust structure.

Installation

npm install -g @typesys/console
npm install @typesys/console

Warning: This package is native ESM and no longer provides a CommonJS export. If your project uses CommonJS, you will have to convert to ESM or use the dynamic import() function. Please don't open issues for questions regarding CommonJS / ESM.

Usage

CLI

• Create new workspace with name cli-ws in current working directory:

console new <cli-ws>
console n <cli-ws>

• Create new workspace with name cli-ws in custom directory:

console new <cli-ws> --path <custom-path>
console n <cli-ws> -p <custom-path>

API

console comes with an easy to use composable API which help you to generate cli workspace from your javascript/typescript.

• Create new workspace with name cli-ws in custom directory:

import { engine } from "@typesys/console";

engine.load().then(() => {
  // create new workspace
  const input = {
    path: "C:/console/",
    config: {
      npm: true,
      git: true
    },
    package: {
      name: "cli-ws",
      version: "1.0.0",
      description: "",
      command: "cli",
      repository: {
        type: "git",
        url: "",
      },
      bugs: {
        url: "",
      }
      author: "",
      license: "ISC"
    }
  };

  engine.commands.new(input).then(() => console.log("Created !!!"));
});

Commands

name	Description
new	Creates a new CLI app workspace

Workspace

new command will create a workspace in local directory when you trigger it using CLI or API. In this section we covered information related to generated workspace.

Structure

below is the generated workspace structure:

📦cli-app
┣ 📂node_modules
┣ 📂src
┃ ┣ 📂bin
┃ ┃ ┗ 📜main.ts
┃ ┗ 📂lib
┃ ┃ ┣ 📂assist
┃ ┃ ┃ ┗ 📜.gitkeep
┃ ┃ ┣ 📂cmd
┃ ┃ ┃ ┗ 📜greet.ts
┃ ┃ ┣ 📂core
┃ ┃ ┃ ┣ 📜commands.ts
┃ ┃ ┃ ┣ 📜engine.ts
┃ ┃ ┃ ┗ 📜errors.ts
┃ ┃ ┗ 📂utils
┃ ┃ ┃ ┗ 📜utility.ts
┣ 📜.eslintignore
┣ 📜.eslintrc.json
┣ 📜.gitignore
┣ 📜package-lock.json
┣ 📜package.json
┗ 📜tsconfig.json

Script(s)	Description
src/bin/main.ts	Application's entry script
src/lib/core/engine.ts	Core engine which orchestrated all commands & it's actions
src/lib/core/commands.ts	Registered all the commands
src/lib/core/errors.ts	Centralized error system, implemented custom Error classes & handle them
src/lib/cmd/*.ts	Registered action method for all commands
src/lib/utils/*.ts	All utility modules
src/lib/assist/*.ts	All helper methods, classes related to command action

Architecture/Design

Build

To build workspace, trigger npm run build command.

Run

After building the application, you can run the application by:

• Execute node --no-warnings=ExperimentalWarning ./dist/bin/main.js <command> <options>

OR

• Execute npm link
• Execute <application-name> <command> <options>

  You will found <application-name> under bin field in package.json file.

Add new command

Prerequisite: Please check Architecture/Design section before adding new command.

workspace use commander npm package to look after parsing the arguments into options and command-arguments, displays usage errors for problems, and implements a help system.

Below steps will add a new command help in the workspace, you can follow the same steps to add your new command and modify corresponding fields.

• Open ./src/lib/core/commands.ts file in code editor.
• Register help command by adding a new entry in program object and expand it based on your requirement.

program
  .command("help")
  .alias("h")
  .description("Show information related to passing command")
  .argument("<command>", "command name")
  .option(
    "-y, --yes",
    "Open command information in default browser. [boolean][Default: false]"
  )
  .action((command, options) => engine.action("help", name, options));

• Create a new file with the name help.ts under ./src/cmd/ directory.
• Open ./src/cmd/help.ts file in code editor.
• Implement two function with name api & cli and export them.

export type HelpInput = {
  name: string;
  browser: boolean;
};

const api = async (input: HelpInput): Promise<void> => {
  // Implement logic

  return Promise.resolve();
};

const cli = async (name: string, options: { yes: boolean }): Promise<void> => {
  const input: HelpInput = {
    name,
    browser: yes
  };

  // Implement user input verification logic
  // Other logic...

  // call api to execute command action
  await api(input);

  return Promise.resolve();
};

export { api, cli };

• Build the application.

Successfully added new command help to the application.