json

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

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>

Overwrites the entire contents of a JSON file with the provided value. If the file does not exist, it will be created.

Parameters

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>

Merges an object with the contents of a JSON file. If the file has the same keys as the passed-in object, the values for those keys will be overwritten. If the file does not exist, it will be created.

Parameters

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>

Removes a property from a JSON file using a lodash style object path.

Parameters

string

required

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`

() => Promise<void>

Deletes a JSON file from disk.

Example

await json('/path/from/root/package.json').delete();

Configuration

CLI

Objects

Utilities

`exists`

Example

`get`

Returns

Example

`contains`

Parameters

Returns

Example

`set`

Parameters

Example

`merge`

Parameters

Example

`remove`

Parameters

Example

`delete`

Example

​exists

​Example

​get

​Returns

​Example

​contains

​Parameters

​Returns

​Example

​set

​Parameters

​Example

​merge

​Parameters

​Example

​remove

​Parameters

​Example

​delete

​Example

`exists`

Example

`get`

Returns

Example

`contains`

Parameters

Returns

Example

`set`

Parameters

Example

`merge`

Parameters

Example

`remove`

Parameters

Example

`delete`

Example