conartist/README.md

# Conartist

Hate managing all your different config files across all your different
repositories? Great. Step into my office.

> Conartist is a tool that gives you a way to manage all of your config files
> from a single source of truth. Not only will it scaffold them out, it can also
> keep them in sync even if you modify them manually.

Major use cases:

- Keeping separate repos in sync.
- Keeping monorepo packages in sync.
- Scaffolding out new projects.

## Install

```sh
npm i -D conartist
```

Conartist can be configured by any one of the following:

- `conartist` field in the `package.json`
- `.conartistrc`
- `.conartistrc.json`
- `.conartistrc.yaml`
- `.conartistrc.yml`
- `.conartistrc.js`
- `.conartist.config.js`

If you use a `.js` file, you will be able to have finer-grained control if you
require it. See the secion on [custom file handlers](#custom-file-handlers) for
more information.

## Usage

If you put the following in a `package.json`.

```json
{
  "conartist": {
    ".gitignore": ["*.log", "node_modules"],
    ".nvmrc": "10.9.0",
    ".travis.yml": "language: node_js"
  }
}
```

Running `$ conartist` will create the specified files relative to the `cwd`.
This is great for scaffolding out a project or keeping it in sync with what the
configuration has in it.

## Built-in file handlers

The following are the built-in - and exported - file handlers.

- [`handeArray`](#async-handlearrayfile-data)
- [`handleJs`](#async-handlejsfile-data)
- [`handleJson`](#async-handlejsonfile-data)
- [`handleString`](#async-handlestringfile-data)

These handlers will handle the following file patterns:

```js
const mapGlob = {
  ".nvmrc": handleString,
  ".*rc": handleJson,
  ".*ignore": handleArray,
  "*.js": handleJs,
  "*.json": handleJson
};
```

And attempt to handle the following value types:

```js
const mapType = {
  object: handleJson
};
```

If a handler cannot be found, it defaults to using `handleString`.

## Custom file handlers

Custom file handlers require a `.js` file in order to be applied. There are two
types of handlers you can use:

- Global
- File-specific

### Global file handlers

Global file handlers handle all files in your configuration file. When you set a
global handler, it overwrites the existing handler, so you must call
[`getHandler`](#gethandler) and callback to it if you want to retain its
functionality around your new one.

You set a new handler by calling [`setHandler`](#sethandler-handler). You are
responsible for returing the string that will be output to the file and for
handling all types of files that you might set in your configuration.

```js
// conartist.config.js

const { getHandler, setHandler } = require("conartist");

const previousHandler = getHandler();

setHandler(function myCustomHandler(file, data) {
  if (file === ".gitignore") {
    return data.join("\n");
  }
  return previousHandler(file, data);
});

module.exports = {
  ".gitignore": ["*.log", "node_modules"]
};
```

### File-specific handlers

File-specific handlers are applied as a function to the corresponding file
instead of other data types. The global file handler will then call this and
write its return value to the file as a priority over any other handler.

_If you overwrite the default global file handler, file-specific handlers will
not work because their behaviour is provided by the default global file handler.
If you need to override the global file handler and still retain this behaviour,
it's up to you to implement it or call back to the default global file handler._

```js
// conartist.config.js

module.exports = {
  ".gitignore": (file, data) => data.join("\n")
};
```

## Use cases

File-specific handlers are a good way to compose in your own behaviour.

### Preventing merging

You may _not_ want to merge JSON data from the config with what's already there,
by default. To override this, all you need to do is provide a function that
returns JSON:

```js
// conartist.config.js

module.exports = {
  "somefile.json": () => ({
    my: "data"
  })
};
```

In the above example, the config file would always overwrite any existing
`somefile.json`. If you would rather the existing file overwrite the config, you
can do something like:

```js
const { loadJson } = require("conartist");

module.exports = {
  "somefile.json": file =>
    loadJson(file) || {
      my: "data"
    }
};
```

### Custom merging

If you would prefer to implement custom merging, you might do something like:

```js
const { loadJson } = require("conartist");

module.exports = {
  "somefile.json": file => ({
    // Putting your data here means that it can
    // be overridden by existing data.
    my: "data",

    // loadJson returns null if no file is found.
    ...(loadJson(file) || {})
  })
};
```

Another use case is composing files together into another file. This can be
useful if you have custom files that you want to compose together into a file.

The following example will take data read from a `package.json` and generate a
`README.md` from it:

```js
const { loadJson } = require("conartist");
const outdent = require("outdent");

module.exports = {
  "README.md": async file => {
    const pkg = await loadJson("package.json");
    return outdent`
      # ${pkg.name}

      > ${pkg.description}
    `;
  }
};
```

_As shown above, you can also use `async` functions for file handlers!_

## API

All exported API points are documented below.

### Global file handling

APIs for handling all files.

#### `getHandler()`

Returns the current file handler.

```js
const { getHandler } = require("conartist");

// function defaultHandler() { ... }
getHandler();
```

#### `setHandler(handler)`

Sets a new file handler, overwriting any current handler. If you require
existing handler functionality, make sure you call `getHandler()` and callback
to it.

```js
const { getHandler, setHandler } = require("conartist");

function customHandler() {}
setHandler(customHandler);

// true
getHandler() === customHandler;
```

### File-specific handling

APIs for handling specific files.

#### `async handleArray(file, data)`

Handles an array.

```js
const { handleArray } = require("conartist");

// my\narray
await handleArray("somefile", ["my", "array"]);
```

#### `async handleJs(file, data)`

Handles JS code depending on the value type and applies it as `module.exports`.

- `typeof` `string` - it is formatted and exported.
- `typeof` `object` - it is stringified, formatted and exported.

```js
const { handleJs } = require("conartist");

// module.exports = { some: "data" };
await handleJs("somefile", { some: "data" });
```

#### `async handleJson(file, data)`

Handles JSON. It can be a `string` or anyting that `JSON.parse()` handles.

```js
const { handleJson } = require("conartist");

// { some: "data" };
await handleJson("somefile", { some: "data" });
```

#### `async handleString(file, data)`

Handles a `string` by ensuring that whatever is passed in is converted to a
`string`.

```js
const { handleString } = require("conartist");

// [object Object]
await handleString("somefile", { some: "data" });
```

### Formatting

APIs for formatting data types.

### `formatCode`

Formats JavaScript code using Prettier and the `babel` parser.

```js
const { formatCode } = require("conartist");

// { some: "data" }
formatCode('{"some":"data"}');
```

### `formatJson`

Formats JSON using `JSON.stringify(json, null, 2)`.

```js
const { formatJson } = require("conartist");

// {
//   "some": "data"
// }
formatJson('{"some":"data"}');
```

### Processing

#### `async process(config)`

Syncs the configuration with what's on the file system using the file handlers.

```js
const { process } = require("conartist");

await process({
  "package.json": { name: "my-project" }
});
```

### Utils

General utils for loading configs and reading files.

#### `async getConfig`

Returns the current configuration from the configuration file.

```js
const { getConfig } = require("conartist");

// { ... }
await getConfig();
```

#### `filePath(file)`

Returns the full path to the file relative to the `cwd`.

```js
const { filePath } = require("conartist");

// "/path/to/cwd/package.json"
filePath("package.json");
```

#### `async loadFile(file)`

Loads a file using `require` relative to the `cwd`. If it does not exist, it
returns `null`.

```js
const { loadFile } = require("conartist");

// { ... }
loadFile("package.json");
```

#### `async readFile(file)`

Reads a file into a `string` relative to the `cwd`. If it does not exist, it
returns `null`.

```js
const { readFile } = require("conartist");

// { ... }
readFile("package.json");
```

#### `async readJson(file)`

Reads a file into JSON relative to the `cwd`. If it does not exist, it returns
`null`.

```js
const { readJson } = require("conartist");

// { ... }
readJson("package.json");
```