cartridge-module-util

    0.5.2 • Public • Published

    Cartridge Module Utilities

    Build Status Commitizen friendly

    This package contains several methods used by Cartridge modules when installing.

    Usage

    When required the module returns a function that expects one argument, an object containing the contents of the calling modules package.json. The function returns the api that Cartridge modules can use.

    Example usage

    var packageConfig = require('../package.json');
    var cartridgeUtil = require('cartridge-module-util')(packageConfig);

    API

    addModuleConfig(pathToConfigFile)

    Moves a configuration file from the module directory to the configuration directory of the project. Returns a promise on completion.

    Arguments

    pathToConfigFile string

    The path to the module config file. This is relative to the module directory.

    Example

    cartridgeUtil.addModuleConfig(path.resolve('_config', 'task.sass.js'));

    addToRc

    Adds the module information to the project .cartridgerc file. Will update the existing entry if one exists rather than adding a second.

    Returns a promise that is fulfilled once the .cartridgerc file is written.

    Example

    cartridgeUtil.addToRc()
        .then(function() {
            // Code to run after completion
        })

    copyFileToProject(copyPath[, destinationPath])

    Copy a single file / directory from the module directory to the cartridge project directory. If the file being copied already exists in the destination path, it will skipped and not overwritten.

    Returns a promise this is fulfilled once the file has been copied.

    Arguments

    copyPath string

    The file path to copy to the project directory. This is relative to the module directory.

    destinationPath string

    Optional argument specifying where the file will be copied to.

    • If provided, this is relative to the cartridge project directory. If the directory copying into does not exist, it is created before copying.
    • If not provided, this defaults to the cartridge project directory root.

    Example

    //File is copied to the root of the project
    cartridgeUtil.copyFileToProject('file-to-copy.js');
     
    //File is copied into the directory 'copy-directory' in the project root.
    cartridgeUtil.copyFileToProject('file-to-copy.js', 'copy-directory');

    copyToProjectDir(copyPaths)

    Copy mutilpe files, directories at once.

    Arguments

    copyPaths array

    Array containing copy and destination paths. Each index contains a copyInfo object, with the contents:

    • copyInfo.copyPath - This is required and specifies what files or directory is to be copied. This is relative to the module directory. If the path already exists before copying it will not be overwritten.
    • copyInfo.destinationPath - This is optional and specifies where in the project directory it will be copied to. If the directory does not exist, it will be created. When this is not provided it, copy destination path will default to the project directory root.

    Returns a promise this is fulfilled when all copy operations have completed.

    Example

    cartridgeUtil.copyToProjectDir([{
        copyPath: 'file-to-copy.js',
    }, {
        copyPath: 'directory/to/copy'
    }, {
        //file1.js is copied into <project-root>/test-directory
        copyPath: 'file1.js',
        destinationPath: 'test-directory'
    }])

    ensureCartridgeExists

    Validates that a .cartridgerc file exists in the current working directory. Exits the process if the file does not exist.

    Example

    cartridgeUtil.ensureCartridgeExists();

    exitIfDevEnvironment

    Stop execution with a non-error exit code if NODE_ENV environment variable equals development. This can be used to stop certain steps from running such as post install scripts, when developing, running CI builds etc.

    • export NODE_ENV=development in a command line window before running cartridgeUtil.exitIfDevEnvironment() will exit out.
    • export NODE_ENV=production in a command line window before running cartridgeUtil.exitIfDevEnvironment() will continue execution unaffected.

    Example

    cartridgeUtil.exitIfDevEnvironment();

    finishInstall

    Logs out a message that the installation has finished and exits the process with a success status. This should be the last function called.


    logMessage(message)

    Log a message out to the console.

    Arguments

    message string

    Message to be displayed on the command line

    Example

    cartridgeUtil.logMessage('Show me on the command line!');

    modifyProjectConfig(transformFunction)

    Modify the project.json config file of a project with the use of a transform function.

    Arguments

    transformFunction function

    Function used to transform the project config.

    The function should expect one argument, a javascript object representing the contents of the project.json file. It should return the modified object.

    Example

    cartridgeUtil.modifyProjectConfig(function(config) {
        if(!config.paths.src.hasOwnProperty('my_module')) {
            config.paths.src.my_module = 'some/path';
        }
        return config;
    });

    removeFromProjectDir(pathList)

    Remove files or folders from the cartridge project directory. Multiple files and folders can be removed in a single call.

    This can be useful when uninstalling a module in a uninstall script.

    This returns a promise that is fulfilled when all paths have been removed.

    Arguments

    pathList array

    An array with each index being the path to remove. The path should be relative to the project directory.

    Example

    cartridgeUtil.removeFromProjectDir([
        'directory/to/delete',
        'file-to-delete.js'
    ])

    removeFromRc

    Remove the module information to the project .cartridgerc file.

    Returns a promise that is fulfilled once the .cartridgerc file is written.

    Example

    cartridgeUtil.removeFromRc()
        .then(function() {
            // Code to run after completion
        })

    removeModuleConfig(pathToModuleConfig)

    Remove the config file at the provided path.

    Returns a promise that is fulfilled once the config file has been deleted.

    Arguments

    pathToModuleConfig string

    The complete path, with the file name and extension, of the config file.

    Example

    cartridgeUtil.removeModuleConfig(path.resolve('_config', 'task.' + TASK_NAME + '.js'));

    addToPackage(dependencies, dependenciesObjectKey)

    Add extra dependencies to the dependency object in cartridge project package.json. The dependencies to add must be stored in the module's package.json as a seperate key.

    Returns a promise that is fulfilled once the dependencies have been added to the package.json

    Arguments

    dependencies object

    Object of the dependencies to add

    dependenciesObjectKey string

    The string of the key of the dependencies e.g. newDependenciesToAdd. This string relates to the key in the package.json, seen below.

    Example

    //package.json
    {
        "dependencies": { ... }
        "newDependenciesToAdd": {
            "dep1": "0.0.1",
            "dep2": "0.0.2"
        }
    }
    //Package json will need to be read seperately
    cartridgeUtil.addToPackage(newDependenciesToAddToObject, 'newDependenciesToAdd')
        .then(function() {
            // Code to run after completion
        })

    cleanExpansionPack

    Remove all traces of the expansion pack. Calling this function deletes the package's node_modules directory and removes it from the package.json dependency object.

    Returns a promise that is fulfilled once expansion pack files have been deleted.

    Due to removing all traces of the installation, this function should be the penultimate function to call, after all other setup code has run but before running finishInstall

    Example

    cartridgeUtil.cleanExpansionPack();

    installDependencies(dependencies, dependenciesObjectKey)

    Programmatically install npm dependencies. The dependencies to add must be stored in the module's package.json as a seperate key.

    Returns a promise that is fulfilled once all dependencies have been installed.

    Arguments

    dependencies object

    Object of the dependencies to add

    dependenciesObjectKey string

    The string of the key of the dependencies e.g. newDependenciesToAdd. This string relates to the key in the package.json, seen below.

    Example

    //package.json
    {
        "dependencies": { ... }
        "newDependenciesToAdd": {
            "dep1": "0.0.1",
            "dep2": "0.0.2"
        }
    }
    //Package json will need to be read seperately
    cartridgeUtil.installDependencies(newDependenciesToAddObject, 'newDependenciesToAdd')
        .then(function() {
            // Code to run after completion
        })

    Development

    Please follow the instructions within the base module development guide when working on this project.

    Testing

    When adding functionality or modifying existing methods you should add unit tests to cover the change. In addition the tests should be run to ensure that existing functionality hasn't been modified. The tests are run with the following command:

    mocha

    Alternatively both the tests and linting can be run with the following command:

    npm test

    To check the code coverage of the current tests run

    npm run cover

    Please make sure that your changes either increase the test coverage or at least maintain the same coverage.

    Install

    npm i cartridge-module-util

    DownloadsWeekly Downloads

    0

    Version

    0.5.2

    License

    MIT

    Last publish

    Collaborators

    • andrewbrandwood
    • bmds
    • codecomputerlove
    • furzeface
    • iamdarrenhall
    • matthewclaffey
    • mmacartney
    • trisashley