toolkit-utils
v0.0.1-alpha.33toolkit-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 |
[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"]