Resettable-file NPM

resettable-file

Resettable files for creating and maintaining boilerplates and configurations

Description

Provides utility class and methods for boilerplate projects to create/copy/remove files, directories and data files (json/yaml). Created files, directories and data files are tracked and recorded to a json file, and modifications done by this library can be undone by reset() method.

Please note that, this module does not try to be a version conrol system. Main purpose of this module is to modify and reverse selected files only.

Synopsis

Written using TypeScript

const ResettableFile = require("resettable-file");

// Set "warn" (default) or "error" for less noise
const resettableFile = new ResettableFile("./registry.json", { logLevel: "info" });

// Track changes by key/value level
const packageData = resettableFile.getDataObjectSync("./package.1.json");

// Modify package.json
packageData.set("scripts.myscript", "some-cmd").set("scripts.ls", "ls -al");

// Write data to file
resettableFile.writeFileSync("some.txt", "Some text data here");

// Create a symbolic link
resettableFile.createSymLinkSync("/some/where/tsconfig.json", "tsconfig.json");

// Create directory tree
resettableFile.createDirSync("some/deep/path");

// Save changes to registry
resettableFile.saveSync();

// Delete created keys in package.json, delete file and symbolic link if not changed
// and delete directory tree if they are empty:
resettableFile.resetSync();

Reset

Can

Delete created files by this library if they are not changed outside.
Delete created symbolic links if they are not changed outside.
Delete created directories,
- if they are empty
- or all files in directories are created by this libray and they are not changed outside.
Reset key/value pairs in data files (modifictions made by this library)
- Delete created keys,
- Create old keys and values for deleted keys,
- Write old values to replaced keys,
- Delete created values from arrays
- Insert deleted values in to arrays (closest index possible)

Can't

Create deleted files.
Create deleted directories.
Replace old content of files (except data files)
Recreate deleted directories
Recreate deleted symbolic links

As seen from what can and can't be done, ResettableFile is a utility to create and modify text based files and data files (json and yaml) and not a backup/version control for deleted files.

API

Classes

DataObject

Kind: global class

DataObject
- new DataObject([data], [options])
- .isChanged : boolean
- .data : Data
- .original : Data
- .snapshot : Data
- .has(props, [t], [f]) ⇒ *
- .hasSubProp(prop, subProps, [t], [f]) ⇒ *
- .get(path) ⇒ *
- .set(path, value, [options]) ⇒ this
- .setObject(data, [options]) ⇒ this
- .remove(path, [options]) ⇒ this
- .reset() ⇒ Array.<Operation>

new DataObject(data, options)

Param	Type	Default	Description
data	Object	{}	Data to be modified.
options	Object		Options
options.track	boolean		Whether to track changes.
options.sortKeys	Array.<string>		List of keys which their values shoud be sorted. Key names be paths like "scripts.test"
options.name	string		Path of the name to be used in logs.
options.format	Format		Data format used for parsing and serializing data.
options.operations	Array.<Operation>		Operations to reset data to its original state.
options.logger	Logger		A looger instance such as winston. Must implement silky, verbose, info, warn, error.

dataObject.isChanged : boolean

Kind: instance property of DataObject
Read only: true

dataObject.data : Data

Kind: instance property of DataObject
Read only: true

dataObject.original : Data

Kind: instance property of DataObject
Read only: true

dataObject.snapshot : Data

Kind: instance property of DataObject
Read only: true

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

Kind: instance method of DataObject
Returns: * -

Param	Type	Default	Description
props	string \| Array.<Path>		Property or properties to look in data
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) ⇒ *

Kind: instance method of DataObject
Returns: * -

Param	Type	Default	Description
prop	Path		Property or properties to look in data
subProps	string \| Array.<Path>		Property or properties to look in data
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(path) ⇒ *

Kind: instance method of DataObject
Returns: * -

Param	Type	Description
path	Path	Path to get data from

dataObject.set(path, value, options) ⇒ this

Kind: instance method of DataObject
Returns: this -

Param	Type	Default	Description
path	Path		Path 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.

dataObject.setObject(data, options) ⇒ this

Kind: instance method of DataObject
Returns: this -

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

dataObject.remove(path, options) ⇒ this

Kind: instance method of DataObject
Returns: this -

Param	Type	Default	Description
path	string \| Array.<Path>		Path or list of paths to remove
options	Object		Options
options.force	boolean	false	Whether to force change even value is altered by user manually.

dataObject.reset() ⇒ Array.<Operation>

Kind: instance method of DataObject
Returns: Array.<Operation> -

ResettableFile

Kind: global class

ResettableFile
- new ResettableFile(registryFile, [options])
- .root : string
- .sourceRoot : string
- .track : boolean
- .logger : BasicLogger
- .logLevel : string
- .fromRoot(...part) ⇒ string
- .fromSourceRoot(...part) ⇒ string
- .isDataFile(projectFile) ⇒ boolean
- .hasFileSync(projectFiles, [t], [f]) ⇒ *
- .isBrokenLink(projectFile) ⇒ boolena
- .saveSync() ⇒ void
- .resetSync() ⇒ void
- .resetFileSync(projectFile) ⇒ void
- .getFileDetailsSync(projectFile, options) ⇒ FileDetail
- .getFileHashSync(projectFile) ⇒ string
- .getDataObjectSync(projectFile, [options]) ⇒ DataObject
- .createSymLinkSync(targetFile, projectFile, [options]) ⇒ void
- .readFileSync(projectFile, [options]) ⇒ *
- .readFileDetailedSync(projectFile, [options]) ⇒ Object
- .writeFileSync(projectFile, data, [options]) ⇒ void
- .deleteFileSync(projectFile, [options]) ⇒ void
- .copyFileSync(sourceFile, projectFile, [options]) ⇒ void
- .createDirSync(projectDir, [options]) ⇒ void
- .deleteDirSync(projectDir, [options]) ⇒ void

new ResettableFile(registryFile, options)

Param	Type	Default	Description
registryFile	string		Path of the registry file. Registry file's directory is also root directory.
options	Object		Options
options.sourceRoot	string		Source root. If provided all source files are calculated relative to this path for copy, symbolic link etc.
options.track	boolean		Sets default tracking option for methods.
options.logLevel	string	"\"warn\""	Sets log level if default logger is used. ("error", "warn", "info", "debug", "verbose", "silly")
options.logger	BasicLogger		A looger instance such as winston. Must implement info, warn, error, verbose, silly.

resettableFile.root : string

Kind: instance property of ResettableFile
Read only: true

resettableFile.sourceRoot : string

Kind: instance property of ResettableFile
Read only: true

resettableFile.track : boolean

Kind: instance property of ResettableFile
Read only: true

resettableFile.logger : BasicLogger

Kind: instance property of ResettableFile
Read only: true

resettableFile.logLevel : string

Kind: instance property of ResettableFile

resettableFile.fromRoot(...part) ⇒ string

Kind: instance method of ResettableFile
Returns: string -

Param	Type	Description
...part	string	Path or path parts to get full path in root.

Example

const resettable = new ResettableFile({ registryFile: "dir/registry.json" });
resettable.fromRoot("path/to/file.txt"); // dir/path/to/file.txt

resettableFile.fromSourceRoot(...part) ⇒ string

Kind: instance method of ResettableFile
Returns: string -

Param	Type	Description
...part	string	Path or path parts to get full path in root.

Example

const resettable = new ResettableFile({ sourceRoot: "sourcedir" });
resettable.fromSourceRoot("path/to/file.txt"); // sourcedir/path/to/file.txt

resettableFile.isDataFile(projectFile) ⇒ boolean

Kind: instance method of ResettableFile
Returns: boolean -

Param	Type	Description
projectFile	string	File to check

resettableFile.hasFileSync(projectFiles, t, f) ⇒ *

Kind: instance method of ResettableFile
Returns: * -

Param	Type	Default	Description
projectFiles	string \| Array.<string>		File or list of files to look in root.
t	*	true	Value to return if any of the files exists in root.
f	*	false	Value to return if none of the files exists in root.

resettableFile.isBrokenLink(projectFile) ⇒ boolena

Kind: instance method of ResettableFile
Returns: boolena -

Param	Type	Description
projectFile	string	Project file to check.

resettableFile.saveSync() ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

resettableFile.resetSync() ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

resettableFile.resetFileSync(projectFile) ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

Param	Type	Description
projectFile	string	File to reset

resettableFile.getFileDetailsSync(projectFile, options) ⇒ FileDetail

Kind: instance method of ResettableFile
Returns: FileDetail -

VError

Param	Type	Description
projectFile	string	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.

resettableFile.getFileHashSync(projectFile) ⇒ string

Kind: instance method of ResettableFile
Returns: string -

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

resettableFile.getDataObjectSync(projectFile, options) ⇒ DataObject

Kind: instance method of ResettableFile
Returns: DataObject -

VError

Param	Type	Default	Description
projectFile	string		File path to read relative to root.
options	Object		Options
options.create	boolean	false	Whether to create file if it does not exist.
options.defaultContent	Object		Default content to write if file is created.
options.throwNotExists	boolean	true	Throw error if file does not exist.
options.format	boolean	file extension	Format to serialize data in given format. (json or yaml) Default is json.
options.createFormat	boolean	"json"	Format to serialize data in given format. (json or yaml) Default is json.
options.track	boolean	this.track	Whether to track file in registry if it is created by module.
options.force	boolean	false	Whether to force write file even it exist.
options.sortKeys	Array.<string>		List of keys which their values shoud be sorted. Key names be paths like "scripts.test"

resettableFile.createSymLinkSync(targetFile, projectFile, options) ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

Param	Type	Default	Description
targetFile	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");

resettableFile.readFileSync(projectFile, options) ⇒ *

Kind: instance method of ResettableFile
Returns: * -

VError

Param	Type	Default	Description
projectFile	string		File to read relative to root.
options	Object		Options
options.create	boolean	false	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.throwNotExists	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.
options.serialize	Format	parse	Whether to serialize content if file is created. (Default is status of parse option)

resettableFile.readFileDetailedSync(projectFile, options) ⇒ Object

Kind: instance method of ResettableFile
Returns: Object -

VError

Param	Type	Default	Description
projectFile	string		File to read relative to project root.
options	Object		Options
options.create	boolean	false	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.throwNotExists	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.
options.serialize	Format	parse	Whether to serialize content if file is created. (Default is status of parse option)

resettableFile.writeFileSync(projectFile, data, options) ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

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.
options.sortKeys	Array		Keys to be sorted. Keys may be given as chained paths. (i.e. a.b.c -> Keys of c would be sorted)

Example

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

resettableFile.deleteFileSync(projectFile, options) ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

Param	Type	Default	Description
projectFile	string		File path relative to paroject root.
options	Object		Options
options.force	boolean	false	Deletes file even it exists and not auto created.
options.track	boolean	this.track	Whether to operate in tracked mode. In non-tracked mode existing files are not deleted if force is not active.
options.log	boolean	true	Whether to log operation.
options.brokenLink	boolean	false	Whether project file is a broken link. Broken links are treated as if they do not exist.

Example

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

resettableFile.copyFileSync(sourceFile, projectFile, options) ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

Param	Type	Default	Description
sourceFile	string		Source file path.
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.

resettableFile.createDirSync(projectDir, options) ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

Param	Type	Default	Description
projectDir	string		Directory path to relative to project root.
options	Object		Options
options.track	boolean	this.track	Whether to track file in registry if it is created by module.
options.logDirs	boolean	true	Whether to log delete operation of sub directories.

Example

project.createDir("path/to/dir"); // Created "path", "to" and "dir" as necessary.

resettableFile.deleteDirSync(projectDir, options) ⇒ void

Kind: instance method of ResettableFile
Throws:

VError

Param	Type	Default	Description
projectDir	string		Destinantion directory to delete.
options	Object		Options
options.force	boolean	false	Deletes directory and it's contents even it is not empty.
options.track	boolean	this.track	Whether to track file in registry if it is created by module.
options.logFiles	boolean	true	Whether to log delete operation of files.
options.logDirs	boolean	true	Whether to log delete operation of sub directories.