Skip to content
πŸ›  A set of reusable classes and utilities for creating toolkits
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
test
.gitignore
.huskyrc.js
.prettierrc.js
README.hbs
README.md
babel.config.js
jest.config.js
package-lock.json
package.json
tsconfig.json
tslint.json

README.md

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

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

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.

  1. If the given path is found, return it.
  2. If the file name has no extension, looks for a file name with the extension in order of ts, js.
  3. 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"]
You can’t perform that action at this time.