package-json
This library allows you to load, manipulate and write the contents of
a package.json
file.
It also provides a changelog detailing any changes
that have been made.
Usage
npm install @financial-times/package-json
loadPackageJson
After loading the specified package.json
file into memory, the loadPackageJson
method returns a collection of methods that can be used for changing the package.json
document and writing those changes back to disk.
const loadPackageJson = require("@financial-times/package-json");
const packageJson = loadPackageJson({ filepath: `filepath/to/package.json` });
Methods returned:
- get
- hasChangesToWrite
- writeChanges
- getField
- setField
- removeField
- requireDependency
- removeDependency
- requireScript
- removeScript
- getChangelog
get
Returns an object representing the current working state of the package.json
document. This may be different to what exists on the file system if changes have not yet been written by calling the writeChanges
method.
packageJson.get();
hasChangesToWrite
Checks if there are file changes to write.
packageJson.hasChangesToWrite(); // true or false
writeChanges
Writes to the package.json
file.
packageJson.writeChanges(); // true
getField
Gets a specific field from the package.json
object, by passing the field as an argument.
packageJson.getField("name"); // "@financial-times/package-json"
setField
Sets the value for a specific field in the package.json
object and returns a changelog entry.
packageJson.setField("name", "newName");
Returns a changelog entry object:
{
"event": "setField",
"field": "name",
"meta": {},
"previousValue": "oldName",
"alreadyExisted": false
}
removeField
Removes a specific field in the package.json
object and returns a changelog entry.
packageJson.removeField("license");
Returns a changelog entry object:
{
"event": "removeField",
"field": "license",
"meta": {},
"previousValue": "MIT",
"alreadyExisted": true
}
requireDependency
Requires a package to exist as a dependency in package.json
.
packageJson.requireDependency({
pkg: "prettier",
version: "1.16.4",
field: "devDependencies"
});
Returns a changelog entry object:
{
"event": "requireDependency",
"field": "devDependencies",
"meta": {
"pkg": "prettier",
"version": "1.16.4"
},
"previousValue": "1.16.3",
"alreadyExisted": true
}
removeDependency
Removes a package as a dependency from package.json
.
packageJson.removeDependency({
pkg: "prettier",
version: "1.16.4",
field: "devDependencies"
});
Returns a changelog entry object, or false
if the dependency doesn't exist:
{
"event": "removeDependency",
"field": "devDependencies",
"meta": {
"pkg": "prettier"
},
"previousValue": "1.16.3",
"alreadyExisted": true
}
requireScript
Requires a script to exist in the scripts
field of package.json
.
packageJson.requireScript({
stage: "test",
command: "npm run unit-test"
});
Returns a changelog entry object:
{
"event": "requireScript",
"field": "scripts",
"meta": {
"stage": "test"
},
"alreadyExisted": true
}
removeScript
Requires a script to exist in the scripts
field of package.json
.
packageJson.removeScript({
stage: "lint"
});
Returns a changelog entry object:
{
"event": "removeScript",
"field": "scripts",
"meta": {
"stage": "lint"
},
"alreadyExisted": true
}
getChangelog
The changelog represents all the changes that have been made to the package.json
object, regardless of whether they have yet been written to the file.
The changelog is made up of entry objects, which all have the following properties:
-
event
- The type of event i.e.setField
,requireDependency
,removeDependency
orrequireScript
-
field
- The field inpackage.json
that was changed -
alreadyExisted
- Flag whether the field already existed -
previousValue
- Previous value of the field -
meta
- An object containing extra details about the change e.g.pkg
,version
,stage
You can access the changelog entries with the following methods:
getChangelog()
getChangelog.asMessages()
getChangelog.lastEntry()
getChangelog.lastEntryAsMessage()
Examples of working with the changelog
packageJson.requireDependency({
pkg: "prettier",
version: "1.16.4",
field: "devDependencies"
});
packageJson.requireScript({
stage: "test",
command: "npm run unit-test"
});
const changelogObjects = packageJson.getChangelog();
/*
[
{
event: "requireDependency",
field: "devDependencies",
meta: {
pkg: "prettier",
version: "1.16.4"
},
previousValue: "1.16.3",
alreadyExisted: true
},
{
event: "requireScript",
field: "scripts",
meta: {
stage: "test"
},
alreadyExisted: true
}
]
*/
const changelogMessages = packageJson.getChangelog.asMessages();
/*
[
"Required package prettier@1.16.4 in devDependencies, previously 1.16.3",
"Required script for stage 'test' (overwrote existing command)"
]
*/
const lastChangelogEntryObject = packageJson.getChangelog.lastEntry();
/*
{
event: "requireScript",
field: "scripts",
meta: {
stage: "test"
},
alreadyExisted: true
}
*/
const lastChangelogEntryMessage = packageJson.getChangelog.lastEntryAsMessage();
// "Required script for stage 'test' (overwrote existing command)"