feat: add merge function

While `join` merges the content of an object into a file, `merge`
merges the content of two files into a third, that can be a
different file or one of the given two

Closes #5

Author: sebastian-altamirano

README.md

@@ -5,7 +5,7 @@
 [![npm version](https://badge.fury.io/js/json-file-handler.svg)](https://badge.fury.io/js/json-file-handler)
 [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
 
-Create or manipulate JSON files with asynchronous `read`, `write` and `join` (using an object) operations.
+Create or manipulate JSON files with asynchronous `read`, `write`, `merge` (two files into a third) and `join` (an object into a file) operations.
 
 ## Table of Contents
 
@@ -14,8 +14,9 @@ Create or manipulate JSON files with asynchronous `read`, `write` and `join` (us
   - [Things to know](#things-to-know)
   - [Error Handling](#error-handling)
 - [Examples](#examples)
-  - [Reading](#reading)
-  - [Joining and Overwriting](#joining-and-overwriting)
+  - [Read](#read)
+  - [Join and Overwrite](#join-and-overwrite)
+  - [Merge](#merge)
 - [API Documentation](#api-documentation)
 - [FAQ](#faq)
 
@@ -72,14 +73,14 @@ const relativeFilePath = '../config/settings.json';
 const absoluteFilePath = path.resolve(__dirname, relativeFilePath);
 ```
 
-Writing functions (`overwrite` and `join`) asks for a third and optional `indentationLevel` parameter, whose value determines how much space is used for indentation when the file is formatted.
+Writing functions (`overwrite`, `merge` and `join`) asks for an optional `indentationLevel` parameter, whose value determines how much space is used for indentation when the file is formatted.
 `JSON.stringify` is responsible for the formatting, so a value less than 1 indicates that no formatting is applied, and a value greater than 10 is ignored.
 
 ### Error Handling
 
 When the functions fails they return a rejected promise with an error that can either be an instance of `JSONFileHandlerError`, if the error was caused by a misuse of the library, or of `Error` (actually is of [`SystemError`](https://nodejs.org/api/errors.html#errors_class_systemerror), but Node does not exposes the class so it can not be checked using `instanceof` operator), if it was caused by violating an operating system constraint, like reading a file that does not exist, or trying to write to a read-only file.
 
-Both types of errors contains a `code` property that can be used to handle them.
+Both types of errors contain the properties `path` (useful when you want to know which file caused the error when you are merging two files or iterating) and `code`, that can be used to handle them.
 Bellow are the error codes that should be checked for each function, classified by kind:
 
 - `read`
@@ -98,14 +99,23 @@ Bellow are the error codes that should be checked for each function, classified
     - `'EPERM'`
     - `'EMFILE'`
     - `'EISDIR'`
+- `merge`
+  - `JSONFileHandlerError`
+    - `'EMPTY_FILE'`
+    - `'NOT_A_JSON'`
+  - `SystemError`
+    - `'ENOENT'`
+    - `'EPERM'`
+    - `'EMFILE'`
+    - `'EISDIR'`
 
 The error codes of `JSONFileHandlerError` are self explanatory, a more detailed explanation of `SystemError` error codes can be found inside [Node documentation](https://nodejs.org/api/errors.html#errors_common_system_errors). Also in the [examples section](#Examples).
 
 ## Examples
 
-Functions can be executed using async/await or promises. `read` example uses promises while `join` example uses async/await.
+Functions can be used with async/await or promises. `read` example uses promises while `join` and `merge` examples use async/await.
 
-### Reading
+### Read
 
 ```js
 import { read as readJSON } from 'json-file-handler';
@@ -142,7 +152,7 @@ readJSON(settingsFilePath)
   });
 ```
 
-### Joining and Overwriting
+### Join and Overwrite
 
 ```js
 import { join as joinJSON } from 'json-file-handler';
@@ -184,6 +194,60 @@ const newSettings = {
 updateSettingsFile(settingsFilePath, newSettings);
 ```
 
+### Merge
+
+```js
+import { merge as mergeJSON } from 'json-file-handler';
+
+const path = require('path');
+
+const mergeCustomSettingsFileIntoSettingsFile = async (
+  settingsFilePath,
+  customSettingsFilePath
+) => {
+  try {
+    await mergeJSON(
+      absoluteSettingsFilePath,
+      absoluteCustomSettingsFilePath,
+      absoluteSettingsFilePath
+    );
+  } catch (error) {
+    switch (error.code) {
+      case 'EMPTY_FILE':
+        // Both files are empty
+        break;
+      case 'NOT_A_JSON':
+        // The content of at least one of the two files can't be read as JSON
+        break;
+      case 'ENOENT':
+        // At least one of the two files doesn't exist
+        break;
+      case 'EPERM':
+        // At least one of the files requires elevated privileges to be read or
+        // written
+        break;
+      case 'EMFILE':
+        // There are too many open file descriptors, so the file can't be
+        // written at this time
+        break;
+      case 'EISDIR':
+        // At least one of the paths is the path of an existing directory
+        break;
+    }
+  }
+};
+
+const settingsFilePath = path.resolve(__dirname, '../config/settings.json');
+const customSettingsFilePath = path.resolve(
+  __dirname,
+  '../../custom-settings.json'
+);
+mergeCustomSettingsFileIntoSettingsFile(
+  settingsFilePath,
+  customSettingsFilePath
+);
+```
+
 ## API Documentation
 
 API documentation can be read at [https://sebastian-altamirano.github.io/json-file-handler/](https://sebastian-altamirano.github.io/json-file-handler/).

src/index.ts

@@ -36,7 +36,7 @@ import { JSONFileHandlerError } from './models/classes';
 import fs from 'fs';
 import path from 'path';
 
-import merge from 'deepmerge';
+import deepMerge from 'deepmerge';
 
 /**
  * Checks if the directory where the file is or will be located exists.
@@ -195,15 +195,15 @@ export const read = async (filePath: string): Promise<object> => {
 };
 
 /**
- * Merges a given content with the content of a JSON file, or creates a new one
- * if it does not exists.
+ * Joins a given content to the content of a JSON file, or creates a new one
+ * if it doesn't exists.
  *
  * @param filePath - The absolute path where the file is or will be located
  * @param jsonContent - The object to be merged or written to the JSON file
  * @param indentationLevel - How much space to use for indentation when
  * formatting
  *
- * @returns A promise that joins or creates the file when resolved
+ * @returns A promise that joins the content or creates the file when resolved
  */
 export const join = async (
   filePath: string,
@@ -213,7 +213,7 @@ export const join = async (
   if (isAnObject(jsonContent)) {
     try {
       const currentJsonContent: object = await read(filePath);
-      const newJsonContent = merge<object>(currentJsonContent, jsonContent);
+      const newJsonContent = deepMerge<object>(currentJsonContent, jsonContent);
       return await write(filePath, newJsonContent, indentationLevel);
     } catch (error) {
       const fileIsEmpty = error.code === 'EMPTY_FILE';
@@ -233,8 +233,79 @@ export const join = async (
   return Promise.reject(notAValidObjectError);
 };
 
+/**
+ * Duplicates a JSON file.
+ *
+ * @param filePath - The absolute path of the file to be duplicated
+ * @param duplicatedFilePath - The absolute path where the file will be
+ * duplicated
+ * @param indentationLevel - How much space to use for indentation when
+ * formatting
+ *
+ * @returns A promise that duplicates the file when resolved
+ */
+const duplicate = async (
+  filePath: string,
+  duplicatedFilePath: string,
+  indentationLevel: number
+): Promise<void> => {
+  try {
+    const fileContent: object = await read(filePath);
+    return await write(duplicatedFilePath, fileContent, indentationLevel);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+};
+
+/**
+ * Merges the content of two JSON files into a third file, or duplicates one of
+ * the files if the other one is empty.
+ *
+ * @param firstFilePath - The absolute path of the first file
+ * @param secondFilePath - The absolute path of the second file
+ * @param mergedFilePath - The absolute path where the file is or will be
+ * located
+ * @param indentationLevel - How much space to use for indentation when
+ * formatting
+ *
+ * @returns A promise that merges the files, or duplicates one of them, when
+ * resolved
+ */
+export const merge = async (
+  firstFilePath: string,
+  secondFilePath: string,
+  mergedFilePath: string,
+  indentationLevel = 2
+): Promise<void> => {
+  let firstFileContent: object;
+  try {
+    firstFileContent = await read(firstFilePath);
+    const secondFileContent: object = await read(secondFilePath);
+    const mergedContent: object = deepMerge<object>(
+      firstFileContent,
+      secondFileContent
+    );
+    return await write(mergedFilePath, mergedContent, indentationLevel);
+  } catch (error) {
+    if (error.code === 'EMPTY_FILE' && firstFilePath !== secondFilePath) {
+      if (error.path === secondFilePath) {
+        // If the the second file is empty, then the first file has content, so
+        // it's duplicated at `mergedFilePath` using `indentationLevel`
+        return write(mergedFilePath, firstFileContent, indentationLevel);
+      } else {
+        // But if the first file is empty, it's not guaranteed that the second
+        // file will have content, `duplicate` takes care of that condition
+        return duplicate(secondFilePath, mergedFilePath, indentationLevel);
+      }
+    } else {
+      return Promise.reject(error);
+    }
+  }
+};
+
 module.exports = {
   read,
   overwrite,
   join,
+  merge,
 };