edit-config

Read, edit, write configuration files.

- Synopsis
- Details
- API
- edit-config
- Type aliases
- FileFormat
- LogLevel
- PredicateFunction
- ValueFunction
- WritableFileFormat
- Classes
- Class: DataFile ‹T›
- Type parameters
- Hierarchy
- Properties
- data
- found
- Accessors
- readOnly
- Methods
- delete
- get
- getModifiedKeys
- has
- merge
- reload
- save
- serialize
- set
- sortKeys
- Static fromData
- Static load
- Class: Manager
- Hierarchy
- Constructors
- constructor
- Methods
- fromData
- load
- loadAll
- saveAll
- Interfaces
- Interface: DataFileFromDataOptions
- Hierarchy
- Properties
- Optional defaultFormat
- Optional logger
- Optional prettierConfig
- Optional readOnly
- Optional rootDataPath
- Optional rootDir
- Optional saveIfChanged
- Interface: DataFileLoadOptions
- Hierarchy
- Properties
- Optional cosmiconfig
- Optional defaultData
- Optional defaultFormat
- Optional logger
- Optional prettierConfig
- Optional readOnly
- Optional rootDataPath
- Optional rootDir
- Optional saveIfChanged
- Interface: Logger
- Hierarchy
- Properties
- log
- Interface: ManagerFromDataOptions
- Hierarchy
- Properties
- Optional defaultFormat
- Optional readOnly
- Optional rootDataPath
- Optional saveIfChanged
- Interface: ManagerLoadOptions
- Hierarchy
- Properties
- Optional cosmiconfig
- Optional defaultData
- Optional defaultFormat
- Optional readOnly
- Optional rootDataPath
- Optional saveIfChanged

Synopsis

Load, Edit & Save Single Config
``ts
import { DataFile, Manager } from "edit-config";
const packageJson = await DataFile.load("package.json");

packageJson
.set("typings", "dist/index.d.ts",")
.set("scripts.build", "tsc")
.set("scripts.test", (value) => ${value} --coverage)
.merge("husky.hooks", { pre-commit: "eslint" })
.merge("devDependencies", (value, key, data, path, dataFile) => ({ "@types/lodash": dataFile.get("dependencies.lodash") }) )
.sortKeys("scripts", { start: ["build", "test", "lint"] });

await packageJson.save();
`

Cosmiconfig: Load, Edit & Save
`ts
// Loads from package.json or configuration file using cosmiconfig. Set true to use default cosmiconfig configuration.
const husky = await DataFile.load("husky", { cosmiconfig: true });
const eslint = await DataFile.load("eslint", { cosmiconfig: { options: cosmiconfigOptions, searchFrom: __dirname } });

husky.set("hooks.pre-commit", "lint-staged");

// Check if cosmiconfig data can be saved, because saving "js" files are not supported.
if (!husky.readOnly) await husky.save();
`

Load, Edit & Save Multiple Config
`ts
// Create manager and load files.
const manager = new Manager({ root: ".", logger: winstonLogger });
const [packageJson, tsconfig] = await manager.loadAll(["package.json", "tsconfig.json"]);
await manager.saveAll();
`

Example Logger
`ts
import { createLogger, format, transports } from "winston";
const logger = createLogger({
level: "debug",
format: format.combine(format.colorize(), format.splat(), format.simple()),
transports: [new transports.Console()],
});

const packageJson = await DataFile.load("package.json", { logger });
`

Conditional Update
`ts
const packageJson = await DataFile.load("package.json");
packageJson
.set("keywords", ["my", "keywords"], { if: (value) => value === undefined })
.merge("scripts", { build: "tsc", test: "jest" }, { if: (value, key, data, path, rootData) => rootData.has("typings") });
`

Details

DataFile class reads JSON, YAML and JS configuration files and writes JSON and YAML files. Manager class is used to manage multiple DataFile classes.

Tips

* Don't forget to add await when chaining async methods: await (await packageJson.reload()).save();

Highlights:

* Provides has, get, set, merge methods based on lodash functions. delete is based on lodash.unset.
* In addition to lodash functionality, manipulation methods accept value function and condition callback function for conditional manipulation.
* load() and loadAll() do not throw even files do not exist. Instead return default data (if provided), or empty object.
* Data manipulation operations do not write to disk until save() or saveAll() called if autoSave is false. (Default behaviour)
* Manager.load() and Manager.loadAll() methods cache loaded files and return cached results in consequencing calls. Use DataFile.reload() to reload from disk.
* Supports winston logger.


API

edit-config

Type aliases

$3

Ƭ FileFormat: "" | "json" | "yaml" | "js"

Defined in types.ts:12

Data file format.

___

$3

Ƭ LogLevel: "error" | "warn" | "info" | "http" | "verbose" | "debug" | "silly"

Defined in types.ts:9

___

$3

Ƭ PredicateFunction: function

Defined in types.ts:29

#### Type declaration:

▸ (value: any, key: Key, data: object, path: Key[], dataFile: DataFile): boolean

Callback function to test whether operation should be performed. If result is false, operation is not performed.

Parameters:

Name | Type | Description |
------ | ------ | ------ |
value | any | is the value to be modified. |
key | Key | is the key of the changed value. |
data | object | is the object/array to get value from. |
path | Key[] | is the full data path of the value in root data. |
dataFile | DataFile | is the DataFile instance. |

___

$3

Ƭ ValueFunction: function

Defined in types.ts:42

#### Type declaration:

▸ (value: any, key: Key, data: object, path: Key[], dataFile: DataFile): any

If a function is provided instead of value, return value of the function is used as new value.

Parameters:

Name | Type | Description |
------ | ------ | ------ |
value | any | is the value to be modified. |
key | Key | is the key of the changed value. |
data | object | is the object/array to get value from. |
path | Key[] | is the full data path of the value in root data. |
dataFile | DataFile | is the DataFile instance. |

___

$3

Ƭ WritableFileFormat: "json" | "yaml"

Defined in types.ts:15

Writeable Data file format.

Classes

Class: DataFile ‹T›

Read, edit and write configuration files.

Type parameters

▪ T: object

Hierarchy

* DataFile

Properties

$3

• data: T

Defined in data-file.ts:45

Actual data

___

$3

• found: boolean

Defined in data-file.ts:48

Whether file exists or cosmiconfig configuration found.

Accessors

$3

• get readOnly(): boolean

Defined in data-file.ts:100

Whether file can be saved using this library.

Returns: boolean

Methods

$3

▸ delete(path: DataPath, __namedParameters: object): this

Defined in data-file.ts:169

Deletes the property at path of file data.

#### Example
`typescript
dataFile
.delete("script.build")
.delete(["scripts", "test"], { if: (value) => value !== "jest" });
`

Parameters:

▪ path: DataPath

is data path of the property to delete.

▪Default value __namedParameters: object= {}

Name | Type | Description |
------ | ------ | ------ |
condition | undefined | function | - |
logger | undefined | Logger | is winston compatible logger to be used when logging. |

Returns: this

___

$3

▸ get(path: DataPath, defaultValue?: any): any

Defined in data-file.ts:129

Gets the value at path of file data. If the resolved value is undefined, the defaultValue is returned in its place.

#### Example
`typescript
dataFile.get("script.build");
dataFile.get(["script", "build"]);
`

Parameters:

Name | Type | Description |
------ | ------ | ------ |
path | DataPath | is data path of the property to get. |
defaultValue? | any | is value to get if path does not exists on data. |

Returns: any

data stored in given object path or default value.

___

$3

▸ getModifiedKeys(__namedParameters: object): object

Defined in data-file.ts:224

Returns deleted and modified keys (paths) in data file. Keys may be filtered by required condition.

#### Example
`typescript
dataFile.getModifiedKeys({ include: "scripts", exclude: ["scripts.validate", "scripts.docs"] });
`

Parameters:

▪Default value __namedParameters: object= {}

Name | Type | Description |
------ | ------ | ------ |
filter | undefined | function | is a filter function to test whether to include key and type in result. |

Returns: object

set and deleted keys

deleted: StringDataPath[]*

set: StringDataPath[]*

___

$3

▸ has(path: DataPath): boolean

Defined in data-file.ts:114

Returns whether given path exists in file data.

#### Example
`typescript
dataFile.has("script.build");
dataFile.has(["script", "build"]);
`

Parameters:

Name | Type | Description |
------ | ------ | ------ |
path | DataPath | is data path of the property to check. |

Returns: boolean

whether path exists.

___

$3

▸ merge(path: DataPath, ...valuesAndOptions: any[]): this

Defined in data-file.ts:196

This method is like assign except that it recursively merges own and inherited enumerable string keyed properties of source objects
into the destination object. Source properties that resolve to undefined are skipped if a destination value exists.
Array and plain object properties are merged recursively. Other objects and value types are overridden by assignment.
Source objects are applied from left to right. Subsequent sources overwrite property assignments of previous sources.

If you would like merge root object (this.data), use empty array [] as path, because undefined, '' and null are valid object keys.
#### Example
`typescript
dataFile.merge("scripts", { build: "tsc", test: "jest", }, { if: (scripts) => scripts.build !== "someCompiler" });
dataFile.merge([], { name: "my-module", version: "1.0.0" });
`

Parameters:

Name | Type | Description |
------ | ------ | ------ |
path | DataPath | is data path of the property to delete. |
...valuesAndOptions | any[] | are objects to merge given path or a function which returns object to be merged. |

Returns: this

___

$3

▸ reload(): Promise‹this›

Defined in data-file.ts:380

Reload data from disk. If file is not present resets data to default data.

Returns: Promise‹this›

___

$3

▸ save(__namedParameters: object): Promise‹void›

Defined in data-file.ts:279

Saves file. If this is a partial data uses only related part by utilizing rootDataPath option.

Parameters:

▪Default value __namedParameters: object= {}

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
logger | Logger | this.#logger | Winston compatible logger to be used when logging. |
throwOnReadOnly | boolean | true | Whether to throw if file is read only. |

Returns: Promise‹void›

___

$3

▸ serialize(wholeFile: boolean): Promise‹string›

Defined in data-file.ts:303

Returns data serialized as text.

Parameters:

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
wholeFile | boolean | false | is whether to serialize whole file when rootDataPath is set. Reads whole file including rootDataPath part and serializes whole file data. |

Returns: Promise‹string›

serialized data as string.

___

$3

▸ set(path: DataPath, value: any, __namedParameters: object): this

Defined in data-file.ts:147

Sets the value at path of file data. If a portion of path doesn't exist, it's created.
Arrays are created for missing index properties while objects are created for all other missing properties.

#### Example
`typescript
dataFile
.set("script.build", "tsc")
.set(["scripts", "test"], "jest", { if: (value) => value !== "mocha" });
`

Parameters:

▪ path: DataPath

is data path of the property to set.

▪ value: any

is value to set or a function which returns value to be set.

▪Default value __namedParameters: object= {}

Name | Type | Description |
------ | ------ | ------ |
condition | undefined | function | - |
logger | undefined | Logger | is winston compatible logger to be used when logging. |

Returns: this

___

$3

▸ sortKeys(path: DataPath, __namedParameters: object): this

Defined in data-file.ts:271

When keys/values added which are previously does not exist, they are added to the end of the file during file write.
This method allows reordering of the keys in given path. Required keys may be put at the beginning and of the order.

If you would like sort root object (this.data) use sort method or, provide use empty array [] as path, because undefined, '' and null are valid object keys.
#### Example
`typescript
dataFile.sortKeys("scripts", { start: ["build", "lint"], end: ["release"] });
dataFile.sortKeys({ start: ["name", "description"], end: ["dependencies", "devDependencies"] });
`

Parameters:

▪ path: DataPath

is data path of the property to order keys of.

▪Default value __namedParameters: object= {}

Name | Type | Description |
------ | ------ | ------ |
end | undefined | string[] | are ordered keys to appear at the end of given path when saved. |
start | undefined | string[] | are ordered keys to appear at the beginning of given path when saved. |

Returns: this

___

$3

▸ fromData(path: string, data: object, options: DataFileFromDataOptions): Promise‹DataFile›

Defined in data-file.ts:344

Creates DataFile instance from given data to be saved for given file path.

Parameters:

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
path | string | - | is path of the file. |
data | object | - | is the data to create DataFile from. |
options | DataFileFromDataOptions | {} | are options. |

Returns: Promise‹DataFile›

DataFile instance.

___

$3

▸ load(path: string, options?: DataFileLoadOptions): Promise‹DataFile›

Defined in data-file.ts:361

Reads data from given file. If file is not present returns default data to be saved with method.

throws if file exists but cannot be parsed.

Parameters:

Name | Type | Description |
------ | ------ | ------ |
path | string | is path of the file. |
options? | DataFileLoadOptions | are options. |

Returns: Promise‹DataFile›

DataFile instance.

Class: Manager

Manage multiple configuration files using DataFile.

Hierarchy

* Manager

Constructors

$3

\+ new Manager(__namedParameters: object): Manager

Defined in manager.ts:14

Creates a manager to manage multiple data files.

Parameters:

▪Default value __namedParameters: object= {} as any

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
logger | Logger | noLogger | is the winston compatible Logger to be used when logging. |
root | string | process.cwd() | is the root path to be used for all relative file paths. |
saveIfChanged | undefined | false | true | - | is whether to save file only if data is changed. Clones initial data deeply to check during save. |

Returns: Manager

Methods

$3

▸ fromData(path: string, data: object, options: ManagerFromDataOptions): Promise‹DataFile›

Defined in manager.ts:67

Creates DataFile instance from given data and returns it. Also caches the data.

Parameters:

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
path | string | - | is the path of the file. Could be an absolute path or relative to root path option provided to Manager |
data | object | - | is the data to create DataFile from. |
options | ManagerFromDataOptions | {} | are options |

Returns: Promise‹DataFile›

DataFile instance.

___

$3

▸ load(path: string, options: ManagerLoadOptions): Promise‹DataFile›

Defined in manager.ts:42

Reads data from given file and caches it. If file is not present, returns default data to be saved with DataFile.save or [[save]} methods.
If same data file requested multiple times returns cached data file. Absolute path of the file is used as cache key.

#### Example
`typescript
manager.load("package.json");
manager.load("eslint", { defaultFormat: "json", cosmiconfig: { options: { packageProp: "eslint" }, searchForm: "some/path" } })
`

Parameters:

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
path | string | - | is the path of the file. Could be an absolute path or relative to root path option provided to Manager. |
options | ManagerLoadOptions | {} | are options |

Returns: Promise‹DataFile›

DataFile instance.

___

$3

▸ loadAll(paths: string[], options: object): Promise‹DataFile[]›

Defined in manager.ts:92

Reads data from all given files and caches them. If same data file requested multiple times returns cached data file. Absolute path of the file is used as cache key.

Parameters:

▪ paths: string[]

are arry of paths of the files. Could be an absolute path or relative to root path option provided to Manager.

▪Default value options: object= {}

are options.

Name | Type | Description |
------ | ------ | ------ |
defaultData? | any | is the default data to be used if file does not exist. |
defaultFormat? | WritableFileFormat | is the default format to be used if file format cannot be determined from file name and content. |
readOnly? | undefined | false | true | - |
saveIfChanged? | undefined | false | true | is whether to save file only if data is changed. Clones initial data deeply to check during save. |

Returns: Promise‹DataFile[]›

___

$3

▸ saveAll(): Promise‹void›

Defined in manager.ts:102

Saves all files.

Returns: Promise‹void›

Interfaces

Interface: DataFileFromDataOptions

DataFile.fromData options.

Hierarchy

* ManagerFromDataOptions

↳ DataFileFromDataOptions

↳ DataFileLoadOptions

Properties

$3

• defaultFormat? : WritableFileFormat

Inherited from ManagerFromDataOptions.defaultFormat

Defined in types.ts:58

The default format to be used if file format cannot be determined from file name and content.

___

$3

• logger? : Logger

Defined in types.ts:78

Winston compatible logger to be used when logging.

___

$3

• prettierConfig? : PrettierConfig

Defined in types.ts:82

Prettier configuration to be used. If not provided determined automatically.

___

$3

• readOnly? : undefined | false | true

Inherited from ManagerFromDataOptions.readOnly

Defined in types.ts:62

Whether file can be saved using this library.

___

$3

• rootDataPath? : DataPath

Inherited from ManagerFromDataOptions.rootDataPath

Defined in types.ts:60

If only some part of the data/config will be used, this is the data path to be used. For example if this is scripts, only script key of the data is loaded.

___

$3

• rootDir? : undefined | string

Defined in types.ts:80

Root directory for file. If provided, relative path is based on this root directory.

___

$3

• saveIfChanged? : undefined | false | true

Inherited from ManagerFromDataOptions.saveIfChanged

Defined in types.ts:64

Whether to save file only if data is changed. Clones initial data deeply to check during save.

Interface: DataFileLoadOptions

[[DatFile.load]] options.

Hierarchy

↳ DataFileFromDataOptions

↳ DataFileLoadOptions

Properties

$3

• cosmiconfig? : boolean | object

Defined in types.ts:90

Whether to use https://www.npmjs.com/package/cosmiconfig to load configuration. Set true for default cosmiconfig options or provide an object with options for cosmiconfig options and searchFrom to provide cosmiconfig.search() parameter.

___

$3

• defaultData? : undefined | object

Defined in types.ts:88

If only some part of the data/config will be used, this is the data path to be used. For example if this is scripts, only script key of the data is loaded.

___

$3

• defaultFormat? : WritableFileFormat

Inherited from ManagerFromDataOptions.defaultFormat

Defined in types.ts:58

The default format to be used if file format cannot be determined from file name and content.

___

$3

• logger? : Logger

Inherited from DataFileFromDataOptions.logger

Defined in types.ts:78

Winston compatible logger to be used when logging.

___

$3

• prettierConfig? : PrettierConfig

Inherited from DataFileFromDataOptions.prettierConfig

Defined in types.ts:82

Prettier configuration to be used. If not provided determined automatically.

___

$3

• readOnly? : undefined | false | true

Inherited from ManagerFromDataOptions.readOnly

Defined in types.ts:62

Whether file can be saved using this library.

___

$3

• rootDataPath? : DataPath

Inherited from ManagerFromDataOptions.rootDataPath

Defined in types.ts:60

If only some part of the data/config will be used, this is the data path to be used. For example if this is scripts, only script key of the data is loaded.

___

$3

• rootDir? : undefined | string

Inherited from DataFileFromDataOptions.rootDir

Defined in types.ts:80

Root directory for file. If provided, relative path is based on this root directory.

___

$3

• saveIfChanged? : undefined | false | true

Inherited from ManagerFromDataOptions.saveIfChanged

Defined in types.ts:64

Whether to save file only if data is changed. Clones initial data deeply to check during save.

Interface: Logger

Logger

Hierarchy

* Logger

Properties

$3

• log: function

Defined in types.ts:6

#### Type declaration:

▸ (...args: Array‹any›): any

Parameters:

Name | Type |
------ | ------ |
...args | Array‹any› |

Interface: ManagerFromDataOptions

Manager.fromData options.

Hierarchy

* ManagerFromDataOptions

↳ ManagerLoadOptions

↳ DataFileFromDataOptions

Properties

$3

• defaultFormat? : WritableFileFormat

Defined in types.ts:58

The default format to be used if file format cannot be determined from file name and content.

___

$3

• readOnly? : undefined | false | true

Defined in types.ts:62

Whether file can be saved using this library.

___

$3

• rootDataPath? : DataPath

Defined in types.ts:60

If only some part of the data/config will be used, this is the data path to be used. For example if this is scripts, only script key of the data is loaded.

___

$3

• saveIfChanged? : undefined | false | true

Defined in types.ts:64

Whether to save file only if data is changed. Clones initial data deeply to check during save.

Interface: ManagerLoadOptions

Manager.load options.

Hierarchy

* ManagerFromDataOptions

↳ ManagerLoadOptions

Properties

$3

• cosmiconfig? : boolean | object

Defined in types.ts:72

Whether to use https://www.npmjs.com/package/cosmiconfig to load configuration. Set true for default cosmiconfig options or provide an object with options for cosmiconfig options and searchFrom to provide cosmiconfig.search() parameter.

___

$3

• defaultData? : any

Defined in types.ts:70

The default data to be used if file does not exist.

___

$3

• defaultFormat? : WritableFileFormat

Inherited from ManagerFromDataOptions.defaultFormat

Defined in types.ts:58

The default format to be used if file format cannot be determined from file name and content.

___

$3

• readOnly? : undefined | false | true

Inherited from ManagerFromDataOptions.readOnly

Defined in types.ts:62

Whether file can be saved using this library.

___

$3

• rootDataPath? : DataPath

Inherited from ManagerFromDataOptions.rootDataPath

Defined in types.ts:60

If only some part of the data/config will be used, this is the data path to be used. For example if this is scripts, only script` key of the data is loaded.

___

$3

• saveIfChanged? : undefined | false | true

Inherited from ManagerFromDataOptions.saveIfChanged

Defined in types.ts:64

Whether to save file only if data is changed. Clones initial data deeply to check during save.