project-helper

Helper for node projects

• Description
• Synopsis
• API
  • Classes
  • Typedefs
  • Project
    • new Project([moduleName], options, debug)
    • project.package : TrackedObject
    • project.name : string
    • project.root : string
    • project.moduleName : string
    • project.moduleRoot : string
    • project.track : boolean
    • project.config : object
    • project.load() ⇒ void
    • project.save() ⇒ Promise.<void>
    • project.resolveModule() ⇒ Promise.<string>
    • project.resolveBin(modName, [options], [executable], [cwd]) ⇒ Promise.<string>
    • project.fromRoot(...part) ⇒ string
    • project.fromModuleRoot(...part) ⇒ string
    • project.hasFile(files, [t], [f]) ⇒ Promise.<*>
    • project.hasAnyDep(deps, [t], [f]) ⇒ *
    • project.envIsSet(name) ⇒ boolean
    • project.parseEnv(name, defaultValue) ⇒ *
    • project.getConcurrentlyArgs(scripts, [options], [killOthers]) ⇒ Array.<string>
    • project.isOptedOut(key, [t], [f]) ⇒ Promise.<*>
    • project.isOptedIn(key, [t], [f]) ⇒ Promise.<*>
    • project.getFileDetails(projectFile, options) ⇒ Promise.<FileDetail>
    • project.createSymLink(moduleFile, projectFile, [options]) ⇒ Promise.<void>
    • project.getFileHash(projectFile) ⇒ string
    • project.getDataFile(projectFile, [options]) ⇒ Promise.<void>
    • project.readFile(projectFile, [options]) ⇒ Promise.<*>
    • project.writeFile(projectFile, data, [options]) ⇒ Promise.<void>
    • project.copyFile(moduleFile, projectFile, [options]) ⇒ Promise.<void>
    • Project~FileDetail : Object
  • DataObject
    • new DataObject([data], [options])
    • dataObject.isChanged : boolean
    • dataObject.data : Object
    • dataObject.has(props, [t], [f]) ⇒ *
    • dataObject.hasSubProp(prop, subProps, [t], [f]) ⇒ *
    • dataObject.get(key) ⇒ *
    • dataObject.set(key, value) ⇒ this
    • dataObject.setObject(data) ⇒ this
    • dataObject.remove(key) ⇒ this
  • TrackedObject
    • new TrackedObject([data], [registry], [options])
    • trackedObject.registry : Object
    • trackedObject.isChanged : boolean
    • trackedObject.data : Object
    • trackedObject.set(key, value, [options]) ⇒ this
    • trackedObject.setObject(data, [options]) ⇒ this
    • trackedObject.remove(key, [options]) ⇒ this
    • trackedObject.has(props, [t], [f]) ⇒ *
    • trackedObject.hasSubProp(prop, subProps, [t], [f]) ⇒ *
    • trackedObject.get(key) ⇒ *
  • Format : "json" | "yaml" | "auto"

Description

Synopsis

API

Classes

Project

Project class

DataObject

This class is used for modifications of the given object.

TrackedObject

This class is used for controlled modifications of the given object. It uses a data object called registry, which stores modifications made by this library. Modifies only data not created or altered by user. Optionally changes may be forced.

Typedefs

Format : "json" | "yaml" | "auto"

Project

Project class

Kind: global class

• Project
  • new Project([moduleName], options, debug)
  • instance
    • .package : TrackedObject
    • .name : string
    • .root : string
    • .moduleName : string
    • .moduleRoot : string
    • .track : boolean
    • .config : object
    • .load() ⇒ void
    • .save() ⇒ Promise.<void>
    • .resolveModule() ⇒ Promise.<string>
    • .resolveBin(modName, [options], [executable], [cwd]) ⇒ Promise.<string>
    • .fromRoot(...part) ⇒ string
    • .fromModuleRoot(...part) ⇒ string
    • .hasFile(files, [t], [f]) ⇒ Promise.<*>
    • .hasAnyDep(deps, [t], [f]) ⇒ *
    • .envIsSet(name) ⇒ boolean
    • .parseEnv(name, defaultValue) ⇒ *
    • .getConcurrentlyArgs(scripts, [options], [killOthers]) ⇒ Array.<string>
    • .isOptedOut(key, [t], [f]) ⇒ Promise.<*>
    • .isOptedIn(key, [t], [f]) ⇒ Promise.<*>
    • .getFileDetails(projectFile, options) ⇒ Promise.<FileDetail>
    • .createSymLink(moduleFile, projectFile, [options]) ⇒ Promise.<void>
    • .getFileHash(projectFile) ⇒ string
    • .getDataFile(projectFile, [options]) ⇒ Promise.<void>
    • .readFile(projectFile, [options]) ⇒ Promise.<*>
    • .writeFile(projectFile, data, [options]) ⇒ Promise.<void>
    • .copyFile(moduleFile, projectFile, [options]) ⇒ Promise.<void>
  • inner
    • ~FileDetail : Object

new Project([moduleName], options, debug)

Param	Type	Default	Description
[moduleName]	string	"[dir of module]"	Module name which provides configuration services to project using this library. Defaults to directory name.
options	Object		Options
debug	boolean		Adds debug data to instance.

project.package : TrackedObject

Object which contains data of package.json of project.

Kind: instance property of Project

project.name : string

Module name which provides configuration services to project using this library.

Kind: instance property of Project
Read only: true

project.root : string

Root directory path of project.

Kind: instance property of Project
Read only: true

project.moduleName : string

Module name which provides configuration services to project using this library.

Kind: instance property of Project
Read only: true

project.moduleRoot : string

Root directory path of module which provides configuration services to project using this library.

Kind: instance property of Project
Read only: true

project.track : boolean

Whteher files of the project are tracked to determine if they are created by the module.

Kind: instance property of Project
Read only: true

project.config : object

Configuration for module.

Kind: instance property of Project
Read only: true

project.load() ⇒ void

Finds project path, loads necessary files (i.e. configuration, registry etc.)

Kind: instance method of Project
Throws:

• VError

Throws error if files cannot be read

project.save() ⇒ Promise.<void>

Saves any changes made to disk.

Kind: instance method of Project
Returns: Promise.<void> -

Void

**Throws**:

• VError

Throws error if files cannot be writeen

project.resolveModule() ⇒ Promise.<string>

Finds and returns path to module's binary. (Module which requires this library)

Kind: instance method of Project
Returns: Promise.<string> -

Path to parent module's binary.

project.resolveBin(modName, [options], [executable], [cwd]) ⇒ Promise.<string>

Finds and returns path of given command.

Kind: instance method of Project
Returns: Promise.<string> -

Path to binary.

**Throws**:

• Error

Throws error no binary cannot be found.

Param	Type	Default	Description
modName	string		Module name to find executable from.
[options]	Object		Options.
[executable]	string	"param.modName"	Executable name. (Defaults to module name)
[cwd]	string	"process.cwd()"	Current working directory

project.fromRoot(...part) ⇒ string

Joins parts to form a path using path.join. Returns path in project by adding project root at the beginning of path.

Kind: instance method of Project
Returns: string -

Full path to project file.

Param	Type	Description
...part	Array.<string>	Path parts to get path relative to project root.

project.fromModuleRoot(...part) ⇒ string

Joins parts to form a path using path.join. Returns path in project by adding project root at the beginning of path.

Kind: instance method of Project
Returns: string -

Full path to project file.

Param	Type	Description
...part	Array.<string>	Path parts to get path relative to project root.

project.hasFile(files, [t], [f]) ⇒ Promise.<*>

Returns one of the given values based on existence of given file path or file paths in project root. Normalizes file path separators based on operating system.

Kind: instance method of Project
Returns: Promise.<*> -

t or f value based on existence of files in project.

Param	Type	Default	Description
files	string | Array.<string>		File or list of files to look in project.
[t]	*	true	Value to return if some of the files exists in project.
[f]	*	false	Value to return if none of the files exists in project.

project.hasAnyDep(deps, [t], [f]) ⇒ *

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: * -

t or f value based on existence of sub property.

Param	Type	Default	Description
deps	string | Array.<string>		Dependency or dependencies to check.
[t]	*	true	Value to return if any of dependencies exists.
[f]	*	false	Value to return if none of dependencies exists.ts.

project.envIsSet(name) ⇒ boolean

Returns whether given environment variable is set and not empty.

Kind: instance method of Project
Returns: boolean -

Whether given environment variable is set and not empty.

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

project.parseEnv(name, defaultValue) ⇒ *

Returns environment variable if it exists and is not empty. Returns given default value otherwise.

Kind: instance method of Project
Returns: * -

Environment variable or default value.

Param	Type	Description
name	string	Name of the environment variable
defaultValue	*	Default value to return if no environment variable is set or is empty.

project.getConcurrentlyArgs(scripts, [options], [killOthers]) ⇒ Array.<string>

Given an object containing keys as script names, values as commands, returns parameters to feed to concurrently.

Kind: instance method of Project
Returns: Array.<string> -

Arguments to use with concurrently.

Param	Type	Default	Description
scripts	Object.<string, string>		Object with script names as keys, commands as values.
[options]	Object		Options
[killOthers]	boolean	true	Whether -kill-others-on-fail should added.

project.isOptedOut(key, [t], [f]) ⇒ Promise.<*>

Returns whether given parameter is opted out.

Kind: instance method of Project
Returns: Promise.<*> -

t or f value based on existence of sub property.

Param	Type	Default	Description
key	string		Paremeter to look for.
[t]	*	true	Value to return if it is opted out.
[f]	*	false	Value to return if it is not opted out.

project.isOptedIn(key, [t], [f]) ⇒ Promise.<*>

Returns whether given parameter is opted in.

Kind: instance method of Project
Returns: Promise.<*> -

t or f value based on existence of sub property.

Param	Type	Default	Description
key	string		Paremeter to look for.
[t]	*	true	Value to return if it is opted in.
[f]	*	false	Value to return if it is not opted in.

project.getFileDetails(projectFile, options) ⇒ Promise.<FileDetail>

Returns file details related to given file path relative to project root.

Kind: instance method of Project
Returns: Promise.<FileDetail> -

File details

**Throws**:

• VError

Throws error if file details cannot be get.

Param	Type	Description
projectFile	string	Project file to get detail for.
options	Object	Options
options.force	boolean	Assume safe to operate on file even it is not auto created.
options.track	boolean	Whether to track file if it is created by module.

project.createSymLink(moduleFile, projectFile, [options]) ⇒ Promise.<void>

Creates a symbolic link in project which points to a file in module. Removes previously created symbolic link created by this library.

Kind: instance method of Project
Returns: Promise.<void> -

Void

**Throws**:

• VError

Throws error if symbolic link cannot be created.

Param	Type	Default	Description
moduleFile	string		Target file which link points to. Should be given relative to module root.
projectFile	string		Link file. Should be given relative to project root.
[options]	Object		Options
[options.force]	boolean	false	Writes file even it exists and not auto created.
[options.track]	boolean	[this.track]	Whether to track symlink if it is created by module.

Example

// Creates tsconfig.json symbolic link file in project root, pointing to a file from toolkit.
createSymLink(here('../../config.json'), 'tsconfig.json');

project.getFileHash(projectFile) ⇒ string

Calculates and returns hash for given file relative to project root.

Kind: instance method of Project
Returns: string -

Calculated hash for file.

Param	Type	Description
projectFile	string	File path of the file relative to project root to calculate hash for.

project.getDataFile(projectFile, [options]) ⇒ Promise.<void>

Kind: instance method of Project
Throws:

• VError

Throws error if file cannot be created.

Param	Type	Default	Description
projectFile	string		File path to read relative to project root.
[options]	Object		Options
[options.format]	boolean	[file extension]	Format to serialize data in given format. (json or yaml) Default is json.
[options.create]	boolean		Whether to create file if it does not exist.
[options.createFormat]	boolean		Format to serialize data in given format. (json or yaml) Default is json.
[options.force]	boolean	false	Whether to force write file even it exist.

project.readFile(projectFile, [options]) ⇒ Promise.<*>

Reads and returns content of the given file relative to project root. Optionally can create file if it does not exist.

Kind: instance method of Project
Returns: Promise.<*> -

Content of the file.

**Throws**:

• VError

Throws error if file cannot be found.

Param	Type	Default	Description
projectFile	string		File to read relative to project root.
[options]	Object		Options
[options.create]	boolean		Whether to create file if it does not exist.
[options.track]	boolean	[this.track]	Whether to track file in registry if it is created by module.
[options.force]	boolean	false	Whether to force create even it is deleted by user.
[options.defaultContent]	*		Default content to write if file does not exist.
[options.errorNotExists]	boolean	true	Throw error if file does not exist.
[options.parse]	boolean	false	Whether to parse file content to create a js object.
[options.format]	Format	[file extension]	Format to use parsing data.
[options.createFormat]	Format	json	Format to be used while creating nonexisting file if no format is provided.

project.writeFile(projectFile, data, [options]) ⇒ Promise.<void>

Creates and writes given data to a file in project.

Kind: instance method of Project
Returns: Promise.<void> -

void

**Throws**:

• VError

Throws error if file cannot be created

Param	Type	Default	Description
projectFile	string		File path to relative to project root.
data	string		Data to write
[options]	Object		Options
[options.force]	boolean	false	Writes file even it exists and not auto created.
[options.track]	boolean	[this.track]	Whether to track file in registry if it is created by module.
[options.serialize]	boolean	false	Whether to serialize object before written to file.
[options.format]	Format	[file extension]	Format to use serializing data.

Example

project.writeFile("./some-config.json", '{"name": "my-project"}'); // Writes given data to some-config.json in project root.

project.copyFile(moduleFile, projectFile, [options]) ⇒ Promise.<void>

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

Kind: instance method of Project
Returns: Promise.<void> -

void

**Throws**:

• VError

Throws error if file cannot be created

Param	Type	Default	Description
moduleFile	string		Source file path relative to module root.
projectFile	string		Destinantion file path relative to paroject root.
[options]	Object		Options
[options.force]	boolean	false	Overwrites file even it exists and not auto created.
[options.track]	boolean	[this.track]	Whether to track file in registry if it is created by module.

Example

project.copy("./some-config.json", "./some-config.json"); // Copies some-config.json file from module's root to project's root.

Project~FileDetail : Object

Type to store file details.

Kind: inner typedef of Project
Properties

Name	Type	Description
isSafe	boolean	Whether it is safe to delete or change given file. (Is true if file is created automatically by module and is not modified by user.)
[stats]	fs.Stats	fs.Stats file details. Undefined if file does not exists.
[linkTarget]	string	If file is a symbolic link, target path relative to module root.

DataObject

This class is used for modifications of the given object.

Kind: global class

• DataObject
  • new DataObject([data], [options])
  • .isChanged : boolean
  • .data : Object
  • .has(props, [t], [f]) ⇒ *
  • .hasSubProp(prop, subProps, [t], [f]) ⇒ *
  • .get(key) ⇒ *
  • .set(key, value) ⇒ this
  • .setObject(data) ⇒ this
  • .remove(key) ⇒ this

new DataObject([data], [options])

Creates an instance of DataObject.

Param	Type	Default	Description
[data]	Object	{}	Data to be modified.
[options]	Object		Options
[options.file]	string		Path of the file to be used in logs.
[options.logger]	Logger		A looger instance such as winston. Must implement verbose, info, warn, error.

dataObject.isChanged : boolean

Whether data is changed.

Kind: instance property of DataObject
Read only: true

dataObject.data : Object

Stored data.

Kind: instance property of DataObject
Read only: true

dataObject.has(props, [t], [f]) ⇒ *

Returns one of the given values based on whether some of given property or properties exists in given object. Property names may be given as chained such as key or key.subkey.

Kind: instance method of DataObject
Returns: * -

t or f value based on existence of property.

Param	Type	Default	Description
props	string | Array.<string>		Property or properties to look in package.json
[t]	*	true	Value to return if some of the properties exists in project.
[f]	*	false	Value to return if none of the properties exists in project.

Example

const result = project.hasProp(['scripts.build', 'scripts.build:doc'], 'yes', 'no');

dataObject.hasSubProp(prop, subProps, [t], [f]) ⇒ *

Returns one of the given values based on whether some of given property path or property paths exists in object's target property path. Property names may be given as chained such as key or key.subkey.

Kind: instance method of DataObject
Returns: * -

t or f value based on existence of sub property.

Param	Type	Default	Description
prop	string		Property or properties to look in package.json
subProps	string | Array.<string>		Property or properties to look in package.json
[t]	*	true	Value to return if some of the properties exists.
[f]	*	false	Value to return if none of the properties exists.

Example

const result = project.hasSubProp('scripts', ['build', 'build:doc']);
const result2 = project.hasSubProp('address.home', ['street.name', 'street.no']);

dataObject.get(key) ⇒ *

Returns data in given key or path. Path may be given as chained. (i.e "scripts.compile")

Kind: instance method of DataObject
Returns: * -

Data stored at given key.

Param	Type	Description
key	string	Key to get data from

dataObject.set(key, value) ⇒ this

Stores given data at given key or path. Based on force option, does not change value if it is not created automatically by this library by looking registry. Path may be given as chained. (i.e "scripts.compile")

Kind: instance method of DataObject
Returns: this -

Object instance.

Param	Type	Description
key	string	Key to store data at.
value	*	Value to store at given key.

dataObject.setObject(data) ⇒ this

Stores each key and its value in the object. Key's may be given as chained paths such as scripts.compile.

Kind: instance method of DataObject
Returns: this -

Object instance.

Param	Type	Description
data	Object	Data to store at object.

Example

data.setObject({ "a.b": 1, c: 2, d: 3 });

dataObject.remove(key) ⇒ this

Removes given path or paths from object . Based on force option, does not remove value if it is not created automatically by this library by looking registry. Path may be given as chained. (i.e "scripts.compile")

Kind: instance method of DataObject
Returns: this -

Object instance.

Param	Type	Description
key	string | Array.<string>	Key or list of keys to remove

TrackedObject

This class is used for controlled modifications of the given object. It uses a data object called registry, which stores modifications made by this library. Modifies only data not created or altered by user. Optionally changes may be forced.

Kind: global class

• TrackedObject
  • new TrackedObject([data], [registry], [options])
  • .registry : Object
  • .isChanged : boolean
  • .data : Object
  • .set(key, value, [options]) ⇒ this
  • .setObject(data, [options]) ⇒ this
  • .remove(key, [options]) ⇒ this
  • .has(props, [t], [f]) ⇒ *
  • .hasSubProp(prop, subProps, [t], [f]) ⇒ *
  • .get(key) ⇒ *

new TrackedObject([data], [registry], [options])

Creates an instance of TrackedObject.

Param	Type	Default	Description
[data]	Object	{}	Data to be modified.
[registry]	Object	{}	Registry object to track changes made by this library. This object stores copies of the data modified by this library.
[options]	Object		Options
[options.file]	string		Path of the file to be used in logs.
[options.logger]	Logger		A looger instance such as winston. Must implement verbose, info, warn, error.

trackedObject.registry : Object

Registry object

Kind: instance property of TrackedObject
Read only: true

trackedObject.isChanged : boolean

Whether data is changed.

Kind: instance property of TrackedObject
Read only: true

trackedObject.data : Object

Stored data.

Kind: instance property of TrackedObject
Read only: true

trackedObject.set(key, value, [options]) ⇒ this

Stores given data at given key or path. Based on force option, does not change value if it is not created automatically by this library by looking registry. Path may be given as chained. (i.e "scripts.compile")

Kind: instance method of TrackedObject
Overrides: set
Returns: this -

Object instance.

Param	Type	Default	Description
key	string		Key to store data at.
value	*		Value to store at given key.
[options]	Object		Options
[options.force]	boolean	false	Whether to force change even value is altered by user manually.

trackedObject.setObject(data, [options]) ⇒ this

Stores each key and its value in the object. Key's may be given as chained paths such as scripts.compile.

Kind: instance method of TrackedObject
Overrides: setObject
Returns: this -

Object instance.

Param	Type	Default	Description
data	Object		Data to store at object.
[options]	Object		Options
[options.force]	boolean	false	Whether to force change even value is altered by user manually.

Example

data.setObject({ "a.b": 1, c: 2, d: 3 });

trackedObject.remove(key, [options]) ⇒ this

Removes given path or paths from object . Based on force option, does not remove value if it is not created automatically by this library by looking registry. Path may be given as chained. (i.e "scripts.compile")

Kind: instance method of TrackedObject
Overrides: remove
Returns: this -

Object instance.

Param	Type	Default	Description
key	string | Array.<string>		Key or list of keys to remove
[options]	object		Options
[options.force]	boolean	false	Whether to force removal even value is altered by user manually.

trackedObject.has(props, [t], [f]) ⇒ *

Returns one of the given values based on whether some of given property or properties exists in given object. Property names may be given as chained such as key or key.subkey.

Kind: instance method of TrackedObject
Returns: * -

t or f value based on existence of property.

Param	Type	Default	Description
props	string | Array.<string>		Property or properties to look in package.json
[t]	*	true	Value to return if some of the properties exists in project.
[f]	*	false	Value to return if none of the properties exists in project.

Example

const result = project.hasProp(['scripts.build', 'scripts.build:doc'], 'yes', 'no');

trackedObject.hasSubProp(prop, subProps, [t], [f]) ⇒ *

Returns one of the given values based on whether some of given property path or property paths exists in object's target property path. Property names may be given as chained such as key or key.subkey.

Kind: instance method of TrackedObject
Returns: * -

t or f value based on existence of sub property.

Param	Type	Default	Description
prop	string		Property or properties to look in package.json
subProps	string | Array.<string>		Property or properties to look in package.json
[t]	*	true	Value to return if some of the properties exists.
[f]	*	false	Value to return if none of the properties exists.

Example

const result = project.hasSubProp('scripts', ['build', 'build:doc']);
const result2 = project.hasSubProp('address.home', ['street.name', 'street.no']);

trackedObject.get(key) ⇒ *

Returns data in given key or path. Path may be given as chained. (i.e "scripts.compile")

Kind: instance method of TrackedObject
Returns: * -

Data stored at given key.

Param	Type	Description
key	string	Key to get data from

Format : "json" | "yaml" | "auto"

Kind: global typedef