toolkit-utils

toolkit-utils

A set of reusable classes and utilities for creating toolkits

⚠️ This is very much work in progress. The API will be facing breaking changes until it is no longer alpha.

Inspired by "Tools without config", "The Melting Pot of JavaScript", and kcd-scripts.

This library provides utility classes and methods for creating toolkits, used to abstract much of the overhead involved in regular JS and TS tasks, such as testing, linting, formatting, building, etc.

• API
  • Classes
  • Functions
  • Project
    • new Project([options])
    • project.srcDir
    • project.scriptsDir
    • project.configDir
    • project.toolkitName
    • project.toolkitRootDir
    • project.name
    • project.package
    • project.isCompiled
    • project.isTypeScript
    • project.toolkitBin
    • project.availableScripts
    • project.fromRoot(...part) ⇒
    • project.fromToolkitRoot(...part) ⇒
    • project.fromConfigDir(...part) ⇒
    • project.fromScriptsDir(...part) ⇒
    • project.hasAnyDep(deps) ⇒
    • project.envIsSet(name) ⇒
    • project.parseEnv(name, defaultValue) ⇒
    • project.packageHas(jsonPath) ⇒
    • project.packageGet(jsonPath) ⇒
    • project.packageSet(jsonPath, value)
    • project.hasScript(scriptFile) ⇒
    • project.hasAnyFile(fileNames)
    • project.writeFile(fileName, data)
    • project.copyFile(sourceFile, newFile)
    • project.bin(executable)
    • project.getConcurrentlyArgs(scripts, killOthers) ⇒
    • project.executeScriptFile(scriptFile, args)
    • project.executeFromCLI(exit) ⇒
    • project.execute(...executables) ⇒ IScriptResult
  • printHelp(scriptNames)
  • replaceArgumentName(args, names, newName) ⇒

API

Classes

Project

The utility class for viewing and manipulating project properties as well as executing scripts.

Functions

printHelp(scriptNames)

Prints the help message including the list of available scripts.

replaceArgumentName(args, names, newName) ⇒

Returns a new array, replacing an argument name with a new name. Does not mutate the original array.

Project

The utility class for viewing and manipulating project properties as well as executing scripts.

Kind: global class

• Project
  • new Project([options])
  • .srcDir
  • .scriptsDir
  • .configDir
  • .toolkitName
  • .toolkitRootDir
  • .name
  • .package
  • .isCompiled
  • .isTypeScript
  • .toolkitBin
  • .availableScripts
  • .fromRoot(...part) ⇒
  • .fromToolkitRoot(...part) ⇒
  • .fromConfigDir(...part) ⇒
  • .fromScriptsDir(...part) ⇒
  • .hasAnyDep(deps) ⇒
  • .envIsSet(name) ⇒
  • .parseEnv(name, defaultValue) ⇒
  • .packageHas(jsonPath) ⇒
  • .packageGet(jsonPath) ⇒
  • .packageSet(jsonPath, value)
  • .hasScript(scriptFile) ⇒
  • .hasAnyFile(fileNames)
  • .writeFile(fileName, data)
  • .copyFile(sourceFile, newFile)
  • .bin(executable)
  • .getConcurrentlyArgs(scripts, killOthers) ⇒
  • .executeScriptFile(scriptFile, args)
  • .executeFromCLI(exit) ⇒
  • .execute(...executables) ⇒ IScriptResult

new Project([options])

The utility class for viewing and manipulating project properties as well as executing scripts.

Param	Description
[options]	Options
[options.debug]	Enables debug logs.
[options.silent]	Silences the logger.
[options.logger]	The instance of Signale to be used as a logger.
[options.filesDir]	The directory of the scripts and config directories. May be the src or lib directory where the toolkit is called from.
[options.toolkitRoot]	The root of the toolkit using this library.

project.srcDir

Path of the src dir in the toolkit.

Kind: instance property of Project

project.scriptsDir

Path of the scripts dir.

Kind: instance property of Project

project.configDir

Path of the config dir.

Kind: instance property of Project

project.toolkitName

The name of the toolkit.

Kind: instance property of Project

project.toolkitRootDir

Path of the root of the toolkit.

Kind: instance property of Project

project.name

The name of the project

Kind: instance property of Project

project.package

The full project package.json object.

Kind: instance property of Project

project.isCompiled

Determine whether a project is compiled via Typescript or Babel.

Kind: instance property of Project

project.isTypeScript

Determine whether a project is a TypeScript project.

Kind: instance property of Project

project.toolkitBin

The command name of the toolkit's bin.

Kind: instance property of Project

project.availableScripts

List of scripts available in this toolkit.

Kind: instance property of Project

project.fromRoot(...part) ⇒

Returns the given path added to the path of the project root. A path may be given as a single string or in multiple parts.

Kind: instance method of Project
Returns:

Path in root directory.

Param	Description
...part	Path relative to the root dir.

project.fromToolkitRoot(...part) ⇒

Returns the given path added to the path of the toolkit root. A path may be given as a single string or in multiple parts.

Kind: instance method of Project
Returns:

Path in toolkit root directory.

Param	Description
...part	Path relative to the root dir of the toolkit.

project.fromConfigDir(...part) ⇒

Returns the given path added to path of the config directory. A path may be given as a single string or in multiple parts.

Kind: instance method of Project
Returns:

Path in config directory.

Param	Description
...part	Path relative to the config dir.

project.fromScriptsDir(...part) ⇒

Returns the given path added to path of the scripts directory. A path may be given as a single string or in multiple parts.

Kind: instance method of Project
Returns:

Path in scripts dir.

Param	Description
...part	Path relative to the scripts dir.

project.hasAnyDep(deps) ⇒

Returns one of the given values based on whether project has any of the given dependencies in dependencies, devDependencies, peerDependencies.

Kind: instance method of Project
Returns:

Boolean value based on the existence of dependency in package.json.

Param	Description
deps	Dependency or dependencies to check.

project.envIsSet(name) ⇒

Checks whether the given environment variable is set.

Kind: instance method of Project
Returns:

Whether the given environment variable is set.

Param	Description
name	Name of the environment variable to look for.

project.parseEnv(name, defaultValue) ⇒

Returns environment variable if it is set. Returns the default value otherwise.

Kind: instance method of Project
Returns:

Environment variable or default value

Param	Description
name	Name of the environment variable to look for.
defaultValue	Default value if the environment variable is not net.

project.packageHas(jsonPath) ⇒

Checks if a given path is a direct property of the package.json

Kind: instance method of Project
Returns:

Whether the given path is in the package file

Param	Description
jsonPath	The path to check

project.packageGet(jsonPath) ⇒

Provides the value at the given path within package.json

Kind: instance method of Project
Returns:

The value at the given path in the package file

Param	Description
jsonPath	The path to get a value from

project.packageSet(jsonPath, value)

Sets the value at the given path within package.json

Kind: instance method of Project

Param	Description
jsonPath	The path to get a value from
value	The value to set at the path

project.hasScript(scriptFile) ⇒

Checks whether the given script exists in the scripts directory.

• If the given path is found, return it.
• If the file name has no extension, looks for a file name with the extension in order of ts, js.
• If the file name with an extension is found, return the full path of the file, including the extension.

Kind: instance method of Project
Returns:

Full path of the script. Null if none is found.

Param	Description
scriptFile	Script file to check for the existance of.

project.hasAnyFile(fileNames)

Checks for a file with a matching filename in the project root.

Kind: instance method of Project

Param	Description
fileNames	The filename(s) including the extension to look for in the project root.

project.writeFile(fileName, data)

Creates and writes the given data to a file in the project.

Kind: instance method of Project

Param	Description
fileName	The name of the file to be written
data	The data to be written to the file. Objects that are provided will be serialized.

project.copyFile(sourceFile, newFile)

Copies a file from the toolkit to the project. Paths should be given relative to the toolkit root and project root.

Kind: instance method of Project

Param	Description
sourceFile	The path to the source file.
newFile	The path to the destination file.

project.bin(executable)

Returns the relative path to an executable located in node_modules/.bin.

Kind: instance method of Project

Param	Description
executable	The name of the executable.

project.getConcurrentlyArgs(scripts, killOthers) ⇒

Given an object with keys as script names and values as commands, return parameters to pass concurrently.

Kind: instance method of Project
Returns:

• Arguments to use with concurrently

Param	Description
scripts	Object with script names as keys and commands as values.
killOthers	Whether all scripts should be killed if one fails.

project.executeScriptFile(scriptFile, args)

Executes a given script file's exported script function. The given script file should be in the "scripts" directory.

Kind: instance method of Project

Param	Description
scriptFile	The script file to execute from the "scripts" directory.
args	A list of arguments to be passed to the script function.

project.executeFromCLI(exit) ⇒

Executes a script based on the script name that was passed in process.argv.

Kind: instance method of Project
Returns:

Result of script

Param	Description
exit	Whether to exit from process.

project.execute(...executables) ⇒ IScriptResult

Executes a binary using spawn.sync with given arguments and returns results. For a single [Executable](Executable), it executes and returns result. For multiple [Executables](Executable), it executes them serially. Execution stops and the function returns result, if one of the commands fails (which adds previous results to result.previousResults). If an object is provided with names as keys and [Executables](Executable) as values, it executes them using concurrently and returns result of concurrently.

Kind: instance method of Project
Returns: IScriptResult -

• Result of the executable.

Param	Type	Description
...executables	Executable	Executable or executables.

Example

// Execute some commands serially and concurrently. Commands in the object are executed concurrently.
// 1. `serial-command-1` is executed first.
// 2. `serial-command-2` is executed second.
// 3. Based on a condition, `serial-command-3` might be executed.
// 4. `build doc command`, `some-other-command`, and `tsc` are executed in parallel. (object keys are names used in logs)
// 5. Lastly, `other-serial-command` is executed.
const result = project.execute(
  ["serial-command-1", ["arg"]],
  "serial-command-2",
  someCondition ? "serial-command-3" : null,
  {
    my-parallel-job: ["build-doc-command", ["arg"],
    my-parallel-task: "some-other-command"
    builder: ["tsc", ["arg"]],
  },
  ["other-serial-command", ["arg"]],
);

printHelp(scriptNames)

Prints the help message including the list of available scripts.

Kind: global function

Param	Description
scriptNames	The list of available scripts.

replaceArgumentName(args, names, newName) ⇒

Returns a new array, replacing an argument name with a new name. Does not mutate the original array.

Kind: global function
Returns:

An array with the arguments replaced.

Param	Description
args	Arguments array.
names	Parameter names to look for in arguments.
newName	Parameter names to look for in arguments.

Example

const arguments = ["--a", "--b"];
replaceArgumentName(arguments, ["--a"], "--c"); // -> ["--c", "--b"]