Merge pull request #99 from dgreene1/disallowSeedWithOptionalNested

Disallow seed with optional nested

Author: dgreene1

README.md

@@ -4,9 +4,28 @@
 
 `mergePartially` is a convenience method for overwriting only the values you want
 
-## I see lots of TypeScript stuff. Can I use this in JavaScript too?
+<!-- toc -->
 
-Yes. Even though the examples are in TypeScript (since it helps to illustrate the problem that `mergePartially` solves), you can just remove the type annotations when using `mergePartially`.
+- [Design Goals](#design-goals)
+- [Why would you want to use this:](#why-would-you-want-to-use-this)
+  * [First, let's try to write the flexible factory function without mergePartially](#first-lets-try-to-write-the-flexible-factory-function-without-mergepartially)
+  * [Now let's refactor using mergePartially](#now-lets-refactor-using-mergepartially)
+- [Examples](#examples)
+- [F.A.Q. / Troubleshooting](#faq--troubleshooting)
+  * [Why wouldn't I just use Object.assign or the spread operator?](#why-wouldnt-i-just-use-objectassign-or-the-spread-operator)
+  * [I see lots of TypeScript stuff. Can I use this in JavaScript too?](#i-see-lots-of-typescript-stuff-can-i-use-this-in-javascript-too)
+  * [What's the difference between .deep and .shallow?](#whats-the-difference-between-deep-and-shallow)
+  * [Why is `.shallow` even necessary?](#why-is-shallow-even-necessary)
+  * [Why is my return type some strange error string?](#why-is-my-return-type-some-strange-error-string)
+- [Contributions](#contributions)
+
+<!-- tocstop -->
+
+## Design Goals
+
+1. the resulting object will always be the same type/`interface` as the seed object
+2. it will always be “Typescript first” so you know the type definitions will not differ at runtime (like many of this library's competitors)
+3. all PRs should allow consumers of the library to feel confident to use this library in production and bullet-proof testing scenarios. High code-coverage percentages gaurantee this.
 
 ## Why would you want to use this:
 
@@ -70,7 +89,7 @@ Wow look how much fewer lines and characters we have to write to accomplish the
 import { mergePartially, NestedPartial } from 'merge-partially';
 
 function makeFakeUser(overrides?: NestedPartial<IUser>): IUser {
-  return mergePartially(
+  return mergePartially.deep(
     {
       id: 1,
       age: 42,
@@ -85,3 +104,63 @@ function makeFakeUser(overrides?: NestedPartial<IUser>): IUser {
 ## Examples
 
 See [the unit tests](https://github.com/dgreene1/merge-partially/blob/master/src/index.spec.ts) for various examples.
+
+## F.A.Q. / Troubleshooting
+
+### Why wouldn't I just use Object.assign or the spread operator?
+
+These two functions have different goals. `Object.assign` can merge two different types into a combination type. `mergePartially` always returns the same type as the seed object. That's one of many reasons why `mergePartially` is safer than `Object.assign`.
+
+### I see lots of TypeScript stuff. Can I use this in JavaScript too?
+
+Yes. Even though the examples are in TypeScript (since it helps to illustrate the problem that `mergePartially` solves), you can just remove the type annotations when using `mergePartially`.
+
+### What's the difference between .deep and .shallow?
+
+- The main difference is that `.deep` allows you to pass multiple levels of partially supplied objects but `.shallow` only allows partial objects at the first level.
+  - On a more technical level, `.deep` allows you to pass in `NestedPartial<T>` as where `.shallow` only accepts `Partial<T>`
+- Both will always return the full object
+
+For example:
+
+```ts
+interface ISeed {
+  a: {
+    b: {
+      c: string;
+      d: string;
+    };
+  };
+}
+
+const seed: ISeed = {
+  a: {
+    b: {
+      c: 'c',
+      d: 'd',
+    },
+  },
+};
+
+const deepResult = mergePartially.deep(seed, { a: { b: { d: 'new d' } } });
+const shallowResult = mergePartially.shallow(seed, {
+  a: {
+    b: {
+      c: 'I had to supply a value for c here but I did not have to supply it in .deep',
+      d: 'new d',
+    },
+  },
+});
+```
+
+### Why is `.shallow` even necessary?
+
+There are some data types that are "less-compatible" with the library and therefore require a workaround ([click here for the description](https://github.com/dgreene1/merge-partially/blob/master/whyShallowInstead.md)). It should be rare that you need to use `.shallow`, but you might prefer `.shallow` over `.deep` anyway for explicitness.
+
+### Why is my return type some strange error string?
+
+In order to meet the design goals (see above), mergePartially proactively prevents certain data combinations. See this link for more information on the soluton: [https://github.com/dgreene1/merge-partially/blob/master/whyShallowInstead.md](https://github.com/dgreene1/merge-partially/blob/master/whyShallowInstead.md)
+
+## Contributions
+
+PRs are welcome. To contribute, please either make a Github issue or find one you'd like to work on, then fork the repo to make the change.