Brica NPM File Manipulation Help Tools

This library can be used to manipulate files and folders as a part of a build process, for instance. Using a single or multiple configuration files it is possible to define and later run different targets. Each target can have multiple actions. The actions can:

• delete files
• delete folders
• delete files in a folder using include and/or exclude filters
• Copy files
• Copy folders
• Copy files using include and/or exclude filters
• Join/concatenate files
• Rename file
• Unlink file or link
• Create symbolic link to a file or a folder
• Change file mode
• Make folders
• Search and replace strings in file with a string or values read from a json file
• Wait on a file

The features are targeting the most used UNIX like file commands mkdir, rm, cp, sed, rename, unlink, link, chmod, waiton etc. with few changes and/or additions.

Install

npm install @pureit/brica --save-dev

Usage

The tool can be started or used in package.json scripts using:

brica target_one [config_file]

You can replace target_one with any of the configured targets. If config_file path is not specified the

.brica.json

in the root of the project is assumed.

Programmatically it can be used with the static execute function:

import { Executer } from '@pureit/brica';
Executer.execute('target_one', 'path_to_config');

var Executer = require("@pureit/brica").Executer;
Executer.execute('target_one', 'path_to_config');

Configure

The easiest configuration is with an assumed file in the root of the project.

.brica.json

Exemple configuration files could be found in the node_modules/@pureit/brica/examples.

The configuration file should start with the proper schema so that your editor can offer help while editing the configuration.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    "target_one: {
        ...
    },
    "target_two": {
        ...
    }
    ...
}

You can create multiple configuration files as well. In that case you will need to supply both target and config file in the call.

Target

Each target groups a number of actions and defines the target usage.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
            ]
    }
    ...
}

• title defines the target usage
• description describes the details about the target
• flags can be used to display title and/or description in the console at the moment of the execution
• actions* are mandatory and define which actions should be executed when the target is ran

Action

Each action can have, in addition to specific ones needed for the execution, one of the following properties:

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "mkdir"
                    "title": "Create dist folder",
                    "flags": ["title"],
                    ...
                }
                ...
            ]
    }
    ...
}

• action* property is mandatory and specifies which action to perform
• title defines the action title and can be used for readability or to print in the console during execution
• flags defines additional behaviour and if it contains 'title' and title property is defined for this action then it will be printed during execution

Action mkdir

This action is used to create a folder. The action will attempt to create the full folder path.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "mkdir",
                    "title": "Create dist folder",
                    "flags": ["title"],
                    "target": "./dist"
                }
                ...
            ]
    }
    ...
}

• action is mkdir
• target specifies the folder to create

Action rm

This action is used to delete files and or folder.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "rm",
                    "title": "Remove LICENSE and unused d.ts files",
                    "target": "./dist/",
                    "exclude": [
                        { "name": "brica\\.d\\.ts", "flags": "i", "dir": false }
                    ],
                    "include": [
                        { "name": ".*\\.d\\.ts", "flags": "i", "dir": false },
                        { "name": "license", "flags": "i", "dir": false }
                    ]
                }
                ...
            ]
    }
    ...
}

• action is rm
• target is the target to delete if it does not include trailing folder separator then the target itself will be also deleted if empty
• exclude if exists defines which files will be skipped (matched via file full path and name regular expression with flags and via optional dir property which represents file or folder)
• include if exists defines which files to include but only if they do not match exclude (matched via file full path and name regular expression with flags and via optional dir property which represents file or folder)

Action cp

This action can be used to copy files or folders and to join/concatenate multiple files into a single file.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "cp",
                    "title": "Copy licenses",
                    "flags": ["title"],
                    "target": "./dist/LICENSE",
                    "source": "./licenses/",
                    "exclude": [
                        { "name": "readme", "flags": "i", "dir": false }
                    ],
                    "include": [
                        { "name": "license", "flags": "i", "dir": false }
                    ],
                    "join": true
                }
                ...
            ]
    }
    ...
}

• action is cp
• target represents destination folder or file in case join is enabled
• source represents source files (if the directory separator is at the end then everything inside the folder will be copied rarther then the folder itself)
• exclude if exists defines which files will be skipped (matched via file full path and name regular expression with flags and via optional dir property which represents file or folder)
• include if exists defines which files to include but only if they do not match exclude (matched via file full path and name regular expression with flags and via optional dir property which represents file or folder)
• join if enabled will join the files into a single file named with target property

Action sed

This action can be used to search and replace text in a target file using regular expressions.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "sed",
                    "title": "Update package.json scripts and dependencies",
                    "flags": ["title"],
                    "target": "./dist/package.json",
                    "replace": [
                        { "find": "\"scripts\"[^{]*{[^}]*}", "flags": "", "replace": "\"scripts\": {}" },
                        { "find": "\"devDependencies\"[^{]*{[^}]*}", "flags": "", "replace": "\"devDependencies\": {}"}
                    ]
                },
                {
                    "action": "sed",
                    "title": "Update LICENSE with version",
                    "flags": ["title"],
                    "target": "./dist/LICENSE",
                    "replace": [
                        { "find": "#version#", "flags": "g", "json": "./dist/package.json", "property": ["version"] }
                    ]
                }
                ...
            ]
    }
    ...
}

• action is sed
• target is the file to change
• replace defines multiple find and replace options using regular expression find and flags
• json JSON file to load for the replacement values if property parm is also defined
• property Property path in json for the value to use to replace the found match if json param is also defined

Action rename

This action can be used to rename a file.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "rename",
                    "title": "Rename licenses.txt to LICENSE",
                    "flags": ["title"],
                    "target": "./dist/LICENSE",
                    "source": "./dist/licenses.txt"
                }
                ...
            ]
    }
    ...
}

• action is rename
• target is the new file name
• source is the existing file to rename

Action unlink

This action can be used to unlink a link or to delete a file.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "unlink",
                    "title": "Remove existing node_modules/@pureit/brica link",
                    "flags": ["title"],
                    "target": "./node_modules/@pureit/brica"
                }
                ...
            ]
    }
    ...
}

• action is unlink
• target is the link or file to delete

Action link

This action can be used to create a symbolic link to file or folder.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "link",
                    "title": "Add new node_modules/@pureit/brica link",
                    "flags": ["title"],
                    "target": "./node_modules/@pureit/brica",
                    "source": "./dist"
                }
                ...
            ]
    }
    ...
}

• action is link
• target is the new link name
• source is the existing file to which link will point

Action chmod

This action can be used to change mode of a file.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "chmod",
                    "title": "Setting executable node_modules/.bin/brica link",
                    "flags": ["title"],
                    "target": "./node_modules/.bin/brica",
                    "mode": "766"
                }
                ...
            ]
    }
    ...
}

• action is chmod
• target is the file whose mode will be changed
• mode is a string containing octal digits for file mode

Action waiton

This action can be used to wait for a file to appear. If the file already exists the action will finish at once.

{
    "$schema": "./node_modules/@pureit/brica/brica.schema.json"
    ...
    "build_step": {
            "title": "Build step",
            "description": "Step during build",
            "flags": [
                "title",
                "description"
            ],
            "actions": [
                ...
                {
                    "action": "waiton",
                    "title": "Waiting for the previous build to finish",
                    "flags": ["title"],
                    "target": "./dist/library.d.ts"
                }
                ...
            ]
    }
    ...
}

• action is waiton
• target is the file that we are waiting for