⚠️ 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

Functions

Project

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])

| 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

Kind: instance property of Project

project.scriptsDir

Kind: instance property of Project

project.configDir

Kind: instance property of Project

project.toolkitName

Kind: instance property of Project

project.toolkitRootDir

Kind: instance property of Project

project.name

Kind: instance property of Project

project.package

Kind: instance property of Project

project.isCompiled

Kind: instance property of Project

project.isTypeScript

Kind: instance property of Project

project.toolkitBin

Kind: instance property of Project

project.availableScripts

Kind: instance property of Project

project.fromRoot(...part) ⇒

Kind: instance method of Project
Returns: Path in root directory.

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

project.fromToolkitRoot(...part) ⇒

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) ⇒

Kind: instance method of Project
Returns: Path in config directory.

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

project.fromScriptsDir(...part) ⇒

Kind: instance method of Project
Returns: Path in scripts dir.

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

project.hasAnyDep(deps) ⇒

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) ⇒

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) ⇒

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) ⇒

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) ⇒

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)

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) ⇒

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)

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)

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)

Kind: instance method of Project

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

project.bin(executable)

Kind: instance method of Project

| Param | Description | | ---------- | ---------------------------------- | | executable | The name of the executable. |

project.getConcurrentlyArgs(scripts, killOthers) ⇒

Kind: instance method of Project
Returns:

| 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)

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) ⇒

Kind: instance method of Project
Returns: Result of script

| Param | Description | | ----- | ------------------------------------ | | exit | Whether to exit from process. |

project.execute(...executables) ⇒ IScriptResult

Kind: instance method of Project
Returns: IScriptResult -

| 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)

Kind: global function

| Param | Description | | ----------- | ------------------------------------- | | scriptNames | The list of available scripts. |

replaceArgumentName(args, names, newName) ⇒

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"]