Documentation Index
Fetch the complete documentation index at: https://docs.commonality.co/llms.txt
Use this file to discover all available pages before exploring further.
The json utility makes it easier to read and write to JSON files within in your checks.
This utility expects an absolute path to a JSON file and returns an object with methods that help you read and write to any JSON file.
To get full type-safety on all returned methods you can pass a generic type to the json function.
import { json } from 'commonality';
const packageJson = json<{ name: string; version: string }>(
'/path/from/root/package.json',
);
exists
Returns a boolean value indicating whether or not the file exists on disk.
Example
const exists = await json('/path/from/root/package.json').exists();
console.log(exists);
// true
get
() => Promise<T extends Record<string, unknown> | undefined>
Returns
Returns the contents of a JSON file as an object. If the file does not exist or is not valid JSON, undefined will be returned.
Example
const packageJson = await json('/path/from/root/package.json').get();
console.log(packageJson);
// {
// "name": "my-package",
// "version": "1.0.0",
// }
contains
(value: Record<string, unknown>) => Promise<boolean>
Parameters
value
Record<string, unknown>
required
An object to check against the JSON file’s contents.
Returns
Returns a boolean value indicating whether or not the object is a subset of the JSON file’s contents. If the file does not exist or is not valid JSON, false will be returned.
Example
const containsValue = await json('/path/from/root/package.json').contains({
name: 'my-package',
});
console.log(containsValue);
// true
set
(value: Record<string, unknown>) => Promise<void>
Parameters
value
Record<string, unknown>
required
An object that will be used to overwrite the JSON file’s contents.
Example
await json('/path/from/root/package.json').set({
name: 'my-package',
version: '1.0.0',
});
merge
(value: Record<string, unknown>) => Promise<void>
Parameters
value
Record<string, unknown>
required
An object that will be deeply merged with the JSON file’s contents.
Example
await json('/path/from/root/package.json').merge({
private: true,
});
remove
(path: string) => Promise<void>
Parameters
A lodash-style path object that will be used to determine which property to remove.
Example
await json('/path/from/root/package.json').remove('scripts.dev');
await json('/path/from/root/package.json').remove(
`dependencies[${dependencyName}]`,
);
delete
Deletes a JSON file from disk.
Example
await json('/path/from/root/package.json').delete();
