@gerard2p/mce

    3.0.1 • Public • Published

    @gerard2p/mce

    semantic-release Commitizen friendly TypeScript
    CI Dependency Status devDependencies Status
    Code Climate Test Coverage Issue Count
    PRs Welcome FOSSA Status

    Installation

    npm i -g @gerard2p/mce

    Usage

        mce new <application> [options]
          Creates a new MCE project.
            -f, --force          Overrides target directory                            
            -n, --npm            Install npm dependencies                              
            -s, --style <style>  Define the style of command you will use. If you need
                                  more than one command use git.
                                  Values: git | *single
        mce add <command>
          Adds a new command to the git project.

    This will create project that is ready to work with mce. The project scaffolding look like this:

    Project Structure

    project_name::
      |--.vscode
      |  |--launch.json
      |  |--settings.json
      |  |--task.json
      |
      |--src
      |  |--index.ts       [single-style]
      |  |--cli.ts
      |  |--commands       [git-style]
      |    |--removeme.ts
      |
      |--.gitignore
      |--package.json
      |--tsconfig.json
      |--project_name
    
    

    Configuring command

    • Single-Style only uses a index.ts in the src folder.
    • Git-Style uses [command].ts files inside the commands folder.

    In any of both cases a command is defined in the same way.

    import { numeric, floating, range, text, list, collect, bool, verbose, enumeration, Parsed} from '@gerard2p/mce';
    import { ok, error, warn, info, ask, input } from '@gerard2p/mce/verbose';
    import { created, updated, makeDir, cp, printRelativePath, targetPath, cliPath } from '@gerard2p/mce/utils';
    import { spin } from '@gerard2p/mce/spinner';
    enum Styles { 
        git = 'git',
        single = 'single' 
    }
    export let description = 'A description for your command';
    export let args = '<arg1> [varidac...]';
    export let options = {
        enumeration: enumeration('-e <enum>', 'Define the style of command you will use', Styles,Styles.single),
        number: numeric('-n <n>', 'A number'),
        floating: floating('-f <n>', 'A float number'),
        range: range('-r <a>..<b>', 'A Range of two numbers'),
        text: text('-t <n>', 'A string value'),
        list: list('-l <n>', 'comma separed values'),
        collect: collect('-c <n>', 'A repetable value'),
        bool: bool('-b', 'A boolean value'),
        verbose: verbose('Increase system verbosity'),
    };
    export async function action(arg1:string, varidac:string[], opt:Parsed<typeof options>) {
        // Your Code
    }

    Option Parsing

    You must export a options variable with the options that you want to use. As you can see you can defined a lot of types for your options most of the options cant take a '' as first parameter and mce will generate the tags for you.

    The name in the you use to define the property is used as main tag, if you pass '' as the first argument it will fill with a automatic tag_desc and no sort tag will be generated. On the other hand if you pass a string like -e --env <env> mce will use those values as the short tag, tag and tag value.

    option short tag tag_desc desc
    enumeration:enumeration('', 'description', ['a','b']) --enumeration <e> description Values a | b
    enumeration:enumeration('-l', 'description', ['a','b']) -l --enumeration <e> description Values a | b
    enumeration:enumeration('-l --list', 'description', ['a','b']) -l --list <e> description Values a | b
    enumeration:enumeration('-l --list <l>', 'description', ['a','b']) -l --list <l> description Values a | b

    No mather the case the actual property that is created in the opt is always enumeration for this case.

    Coercion

    As you can see mce come with some handy functios to coerce and validate the user input.

    import { numeric, floating, range, text, list, collect, bool, verbose, enumeration } from '@gerard2p/mce';

    Validation

    If you need to validate the information of any of your arguments you can pass a RegExp as the third arguments of the option_functions

    import { text } from '@gerard2p/mce';
    
    export let options = {
     size: text('-s --size <size>', 'Pizza size', /^(large|medium|small)$/);
    }
    

    Defaults

    The last argument you pass will always be the default value.

    import { text } from '@gerard2p/mce';
    
    export let options = {
     size: text('-s --size <size>', 'Pizza size', /^(large|medium|small)$/, 'medium');
    }
    

    Version option

    By default mce will trace the --version tag and will respond with the version in your package.json.

    Verbose option

    By default mce will trace the -v --verbose tag and will respond wwith the version in your package.json.

    Only if you define a verbose obtion you will be passed with the actual verbose value but in most of the cases is no needed.

    Arguments

    You need to export a args:string property with you arguments definition

    Required args

    <arg> is the convention to make your arg required is no arg detected mce will throw and error.

    Optional args

    [arg] is the convention to make your arg optional.

    Varidac args

    [arg ...] is the convention to make the rest of the args be presented as varidad string[]

    Coecion

    Argument can be coerced by default they are treated as string but if you use:

    • <arg:number> will be coerce to number.
    • <arg:boolean> will be coerce to boolean.

    Help Generation

    By default mce will trace the -h --help options and will automatically render help

    Add a new command to project

    Just run:

    mce add <command>

    Adds a new command to a git-style project.

    Useful Utilities

    MCE con with a handy bunch of utilities to help you build your commands easily.

    Input

    import { confirm, override, question} from '@gerard2p/mce/input'

    question(display:string)=>Promise<string>

    This is the basic function that allows you to wait for user input. Is compatible with the spinner, so, whenever you call this functions the spinner will stop and display the new message.

    When the user enters the input the spinner will continue working as expected.

    let answer = await question('Are you ready?')
    

    Will display

    Are you ready? _
    

    And will wait for user input.

    if inside a spinner:

    await spin('demo', async ()=>{
     let answer = await question('Are you ready?')
    });
    
    demo - Are you ready? _
    

    confirm (display:string)=>Promise<boolean>

    if(await confirm('Are you ready')) {
     // code
    }
    // Are you ready? [y/n]: _
    await spin('demo', async ()=>{
     if(await confirm('Are you ready')) {
      // code
     }
    });
    // demo - Are you ready? [y/n]: _

    override (display:string, testdir:string, state:boolean)=>Promise<boolean>

    Returns true if safe to write the directory and content. Removes the directory if is needed.

    if(await override('Path already exists do you want to continue')) {
     // code
    }
    // Path already exists do you want to continue? [y/n]: _
    await spin('demo', async ()=>{
     if(await override('Path already exists do you want to continue')) {
      // code
     }
    });
    // demo - Path already exists do you want to continue? [y/n]: _

    tree-maker

    import { pathResolver } from '@gerard2p/mce/tree-maker/fs'

    This function allows you to intersect the path that resolves to your templates and the target path.

    pathResolver(_template:(path:string)=>string, _target?:(path:string)=>string):void

    _template will resolve to a template folder located next to your package.json

    import { cpy, cmp, dir, root, wrt } from '@gerard2p/mce/tree-maker'
    import {   c,   z,   d,    r,   w } from '@gerard2p/mce/tree-maker'

    This utility allows to create a directory structure in a really easy and chainable way.

    root('proyect')
     .with(
      cpy('LICENSE')
     )
     .dir('subfolder',
     cmp('README.md', {...values}, 'DOC.md'),
      cmp('README.md', {...values}),
      wrt('.gitignore','node_modules\ttemplates')
     )

    will produde:

    proyect
      |- LICENSE
      |-subfolder
        |-DOC.md
        |-README.md
        |-.gitignore

    root(dir:string)=>TreeMaker

    Creates the initial directory.

    cpy(source:string, target:string)=>chainable

    Copies a file from your template directory to the destination folder. Target can be undefined and will use the same name as your source.

    cmp(source:string, data:any, target:string)=>chainable

    Renders a file from your template directory to the destination folder. Target can be undefined and will use the same name as your source.

    wrt(target:string, content:string)=>chainable

    Create a file at target location.

    dir(folder:string, ...operations:chainable[])=>chainable

    Create a new directory and allows to chain new operations

    Final Notes

    The executable file that is generated only call your ./cli file.

    When in git-style cli.ts will look like:

    import { MCE } from "@gerard2p/mce";
    
    MCE(__dirname).subcommand(process.argv);

    And in single-style:

    import { MCE } from "@gerard2p/mce";
    
    MCE(__dirname).command(process.argv);

    During local development I use ts-node to call direct the .ts files

    Install

    npm i @gerard2p/mce

    DownloadsWeekly Downloads

    10

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    195 kB

    Total Files

    148

    Last publish

    Collaborators

    • gerard2p