New: Deep-merge props by default

Author: ejhammond

README.md

@@ -238,9 +238,9 @@ export const { ScreenClassProvider, responsive } = createResponsiveSystem({
 });
 ```
 
-## Custom Merge Function
+### Merging
 
-By default, Responsive System will apply any screen-size-specific overrides right on top of your base props, but sometimes you need more control over how your overrides are applied.
+Overrides are applied via [deepmerge](https://www.npmjs.com/package/deepmerge) which means that you can easily apply overrides in arbitrarily-nested objects.
 
 Let's say you've got a component that accepts an `object` as a prop. The intrinsic `style` prop is a great example!
 
@@ -264,50 +264,34 @@ And we can override the style on `small` screens.
 />
 ```
 
-In this case, we might want to override the `backgroundColor` but to leave the `height` alone. But, by default the `small.style` is going to completely override the base `style` and the result on small screens will effectively be:
+A naive override algorithm would simply replace the base `style` with `small.style` and the result would be `style = { backgroundColor: 'blue' }`.
 
-```jsx
-// no height! Bummer...
-<div style={{ backgroundColor: 'blue' }}>
-```
+However, by utilizing `deepmerge` we get `style = { height: 100, backgroundColor: 'blue' }` which is what we'd expect.
 
-We can fix this by providing a `function` as a prop rather than an object. The function will be invoked with the base props as an argument so that you can have full control over how the overrides are handled.
+#### Arrays
 
-```js
-<ResponsiveDiv
-  style={{ height: 100, backgroundColor: 'black' }}
-  small={(baseProps) => {
-    return {
-      ...baseProps,
-      style: { ...baseProps.style, backgroundColor: 'blue' },
-    };
-  }}
-/>
-```
+Merging arrays is tricky, but we've chosen a method that seems like a sane default. If there's a need for customization of the array-merge algorithm, we could support that in a future release.
 
-And voila! Your overrides are applied on your terms.
+For now, the behavior is to treat them like we treat objects. That is, if the base array defines an item at `[0]` and the override array defines an item at `[0]`, the `override[0]` will be merged on top of `base[0]`. Here are a few examples:
 
-### Optimizing
+```txt
+base     [1, 2, 3, 4]
+override [5, 6, 7]
+result   [5, 6, 7, 4]
+```
 
-Pro tip: if you've got a bunch of screen classes that all need to perform custom overrides in the same way, you can create a helper function.
+```txt
+base     [1, 2, 3]
+override [5, 6, 7, 8]
+result   [5, 6, 7, 8]
+```
 
-```jsx
-function makeOverrideFn(overrides) {
-  // function that returns a function!
-  return (baseProps) => {
-    return {
-      ...baseProps,
-      style: { ...baseProps.style, ...overrides },
-    };
-  };
-}
+Objects inside of an array are merged too! Objects and arrays can be nested arbitrarily deep, but keep in mind that merging deeply-nested structures will require our merge algorithm to do more work which could impact performance. It's best to keep your props as shallow as possible.
 
-<ResponsiveDiv
-  style={{ height: 100, backgroundColor: 'black' }}
-  small={makeOverrideFn({ backgroundColor: 'blue' })}
-  medium={makeOverrideFn({ backgroundColor: 'green' })}
-  large={makeOverrideFn({ backgroundColor: 'purple' })}
-/>;
+```txt
+base     [{ a: 'alpha' }, 1]
+override [{ b: 'bravo' }, 2]
+result   [{ a: 'alpha', b: 'bravo' }, 2]
 ```
 
 ## Goodies

examples/gatsby/yarn.lock

@@ -3629,7 +3629,7 @@ deep-is@~0.1.3:
   resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.3.tgz#b369d6fb5dbc13eecf524f91b070feedc357cf34"
   integrity sha1-s2nW+128E+7PUk+RsHD+7cNXzzQ=
 
-deepmerge@^4.0.0:
+deepmerge@^4.0.0, deepmerge@^4.2.2:
   version "4.2.2"
   resolved "https://registry.yarnpkg.com/deepmerge/-/deepmerge-4.2.2.tgz#44d2ea3679b8f4d4ffba33f03d865fc1e7bf4955"
   integrity sha512-FJ3UgI4gIl+PHZm53knsuSFpE+nESMr7M4v9QcgB7S63Kj/6WqMiFQJpBBYz1Pt+66bZpP3Q7Lye0Oo9MPKEdg==
@@ -9675,10 +9675,10 @@ react-reconciler@^0.21.0:
     prop-types "^15.6.2"
     scheduler "^0.15.0"
 
-react-responsive-system@^0.4.1:
-  version "0.4.1"
-  resolved "https://registry.yarnpkg.com/react-responsive-system/-/react-responsive-system-0.4.1.tgz#59fa94ea20e2c8e48bb28f7fc3f236a5dba9db2e"
-  integrity sha512-jq6V0XWXlUGZhlANGpk0V9XDiYvYaNSvDcVsA0A5fLfTfOI0jCPl1/VjqSq5ikCaVO9nbqtcATD+z8YUSbzCdA==
+react-responsive-system@../../:
+  version "0.7.0"
+  dependencies:
+    deepmerge "^4.2.2"
 
 react-side-effect@^1.1.0:
   version "1.1.5"

package.json

@@ -44,5 +44,7 @@
     "tslib": "^1.10.0",
     "typescript": "^3.7.2"
   },
-  "dependencies": {}
+  "dependencies": {
+    "deepmerge": "^4.2.2"
+  }
 }

src/index.tsx

@@ -1,4 +1,6 @@
 import * as React from 'react';
+import { merge } from './merge';
+import { omit } from './omit';
 
 //
 // ─── HELPERS ────────────────────────────────────────────────────────────────────
@@ -7,34 +9,6 @@ import * as React from 'react';
 // keep track of whether or not we have access to `window` (so that we don't crash during e.g. server-side rendering)
 const windowExists = typeof window === 'object';
 
-/**
- * Omits the given keys from the given object
- */
-export default function omit<T extends { [key: string]: any }, K extends keyof T>(
-  obj: T,
-  omittedKeys: K[],
-): Omit<T, K> {
-  // TypeScript assigns the return type, string[] - we are asserting that the return type keyof T
-  const allKeys = Object.keys(obj) as (keyof T)[];
-
-  return allKeys.reduce<Partial<Omit<T, K>>>((acc, key) => {
-    // `omittedKeys.indexOf` expects an input of type K extends keyof T
-    // `key` is type keyof T, but for some reason TypeScript is freaking out
-    // idk.
-    const shouldOmit = omittedKeys.indexOf(key as K) !== -1;
-
-    if (!shouldOmit) {
-      // assert that if we got this far, `key` must be one of the keys that _does not_ exist in K
-      const keptKey = key as Exclude<keyof T, K>;
-
-      acc[keptKey] = obj[keptKey];
-    }
-
-    return acc;
-    // assert that the output is exactly Omit<T, K> rather than Partial<Omit<T, K>>
-  }, {}) as Omit<T, K>;
-}
-
 //
 // ─── TYPES ──────────────────────────────────────────────────────────────────────
 //
@@ -290,14 +264,8 @@ export function createResponsiveSystem<B extends ScreenClassBreakpoints>(
     // e.g. mobile-first should apply smallest -> largest
     // e.g. desktop-first should apply largest -> smallest
     // we assume that the sorting is already done
-    return applicableScreenClasses.reduce((o, sc) => {
-      const override = props[sc] ?? {};
-      if (typeof override === 'function') {
-        return override(o);
-      } else {
-        return { ...o, ...override };
-      }
-    }, baseProps);
+    const propsToMerge = [baseProps, ...applicableScreenClasses.map((sc) => props[sc] ?? {})];
+    return merge(propsToMerge);
   }
 
   // In order to support refs, we need to use forwardRef

src/merge.ts

@@ -0,0 +1,36 @@
+import deepMerge from 'deepmerge';
+
+type MergeArrayHelpers = deepMerge.Options & {
+  cloneUnlessOtherwiseSpecified: <T>(item: T, options: MergeArrayHelpers) => T;
+  isMergeableObject: <T>(item: T) => boolean;
+};
+
+function mergeArrays(base: any[], override: any[], helpers: MergeArrayHelpers) {
+  const { cloneUnlessOtherwiseSpecified, isMergeableObject } = helpers;
+
+  // clone the target array
+  const final = [...base];
+
+  override.forEach((overrideItem, index) => {
+    const baseItem = base[index];
+
+    if (isMergeableObject(overrideItem)) {
+      // if we encounter a "mergeable" object, merge it with the base item
+      /* eslint-disable @typescript-eslint/no-use-before-define */
+      final[index] = mergeTwo(baseItem, overrideItem);
+    } else {
+      // otherwise just replace whatever was in the base array with the override
+      final[index] = cloneUnlessOtherwiseSpecified(overrideItem, helpers);
+    }
+  });
+
+  return final;
+}
+
+function mergeTwo<P extends {}>(base: Partial<P>, override: Partial<P>) {
+  return deepMerge(base, override, { arrayMerge: mergeArrays });
+}
+
+export function merge<P extends {}>(propsObjects: Partial<P>[]) {
+  return deepMerge.all<P>(propsObjects, { arrayMerge: mergeArrays });
+}

src/omit.ts

@@ -0,0 +1,27 @@
+/**
+ * Omits the given keys from the given object
+ */
+export function omit<T extends { [key: string]: any }, K extends keyof T>(
+  obj: T,
+  omittedKeys: K[],
+): Omit<T, K> {
+  // TypeScript assigns the return type, string[] - we are asserting that the return type keyof T
+  const allKeys = Object.keys(obj) as (keyof T)[];
+
+  return allKeys.reduce<Partial<Omit<T, K>>>((acc, key) => {
+    // `omittedKeys.indexOf` expects an input of type K extends keyof T
+    // `key` is type keyof T, but for some reason TypeScript is freaking out
+    // idk.
+    const shouldOmit = omittedKeys.indexOf(key as K) !== -1;
+
+    if (!shouldOmit) {
+      // assert that if we got this far, `key` must be one of the keys that _does not_ exist in K
+      const keptKey = key as Exclude<keyof T, K>;
+
+      acc[keptKey] = obj[keptKey];
+    }
+
+    return acc;
+    // assert that the output is exactly Omit<T, K> rather than Partial<Omit<T, K>>
+  }, {}) as Omit<T, K>;
+}

test/merge.spec.tsx

@@ -0,0 +1,39 @@
+import { merge } from '../src/merge';
+
+it('merges same-length arrays', () => {
+  const a = { array: [1, 2, 3] };
+  const b = { array: [2, 4, 6] };
+
+  expect(merge([a, b])).toStrictEqual({ array: [2, 4, 6] });
+});
+
+it('merges base-longer arrays', () => {
+  const a = { array: [1, 2, 3, 4] };
+  const b = { array: [2, 4, 6] };
+
+  expect(merge([a, b])).toStrictEqual({ array: [2, 4, 6, 4] });
+});
+
+it('merges override-longer arrays', () => {
+  const a = { array: [1, 2, 3] };
+  const b = { array: [2, 4, 6, 8] };
+
+  expect(merge([a, b])).toStrictEqual({ array: [2, 4, 6, 8] });
+});
+
+it('merges objects inside of arrays', () => {
+  const a = { array: [{ one: 1 }, 2, 3] };
+  const b = { array: [{ two: 2 }, 3, 4] };
+
+  expect(
+    merge<any>([a, b]),
+  ).toStrictEqual({ array: [{ one: 1, two: 2 }, 3, 4] });
+});
+
+it('merges objects in order', () => {
+  const a = { foo: 1, alpha: true };
+  const b = { foo: 2, bravo: true };
+  const c = { foo: 3, charlie: true };
+
+  expect(merge([a, b, c])).toStrictEqual({ foo: 3, alpha: true, bravo: true, charlie: true });
+});

yarn.lock

@@ -2901,6 +2901,11 @@ deep-is@~0.1.3:
   resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.3.tgz#b369d6fb5dbc13eecf524f91b070feedc357cf34"
   integrity sha1-s2nW+128E+7PUk+RsHD+7cNXzzQ=
 
+deepmerge@^4.2.2:
+  version "4.2.2"
+  resolved "https://registry.yarnpkg.com/deepmerge/-/deepmerge-4.2.2.tgz#44d2ea3679b8f4d4ffba33f03d865fc1e7bf4955"
+  integrity sha512-FJ3UgI4gIl+PHZm53knsuSFpE+nESMr7M4v9QcgB7S63Kj/6WqMiFQJpBBYz1Pt+66bZpP3Q7Lye0Oo9MPKEdg==
+
 defaults@^1.0.3:
   version "1.0.3"
   resolved "https://registry.yarnpkg.com/defaults/-/defaults-1.0.3.tgz#c656051e9817d9ff08ed881477f3fe4019f3ef7d"