Add ability to pass in custom getLocation 🥳

src/lib/history.js

@@ -1,12 +1,14 @@
-let getLocation = source => {
+let defaultGetLocation = source => {
   return {
     ...source.location,
     state: source.history.state,
     key: (source.history.state && source.history.state.key) || "initial"
   };
 };
 
-let createHistory = (source, options) => {
+let createHistory = (source, options = {}) => {
+  let { getLocation = defaultGetLocation } = options;
+
   let listeners = [];
   let location = getLocation(source);
   let transitioning = false;

src/lib/history.test.js

@@ -0,0 +1,28 @@
+import { createHistory, createMemorySource } from "./history";
+
+describe("createHistory", () => {
+  test("should use default getLocation if not passed in through options", () => {
+    let history = createHistory(createMemorySource());
+    expect(history.location).toHaveProperty("pathname", "/");
+  });
+
+  test("should use custom getLocation", () => {
+    let options = {
+      getLocation(source) {
+        const params = new URLSearchParams(source.location.search);
+
+        return {
+          ...source.location,
+          query: params,
+          state: window.history.state,
+          key: (window.history.state && window.history.state.key) || "initial"
+        };
+      }
+    };
+    let history = createHistory(createMemorySource("/"), options);
+    history.navigate("?yo=dawg");
+
+    expect(history.location.query).toBeInstanceOf(URLSearchParams);
+    expect(history.location.query.get("yo")).toEqual("dawg");
+  });
+});

website/src/markdown/api/createHistory.md

@@ -15,3 +15,33 @@ let history = createHistory(window)
 let source = createMemorySource("/starting/url")
 let history = createHistory(source)
 ```
+
+There may be times within your screen where you may need to change a part of the UI based on some query param. By default we do not parse the search property of the source `location`. To do so we allow you to pass in a custom `getLocation` function into the options object. For example:
+
+```jsx
+import {
+  createMemorySource,
+  createHistory
+} from "@reach/router"
+
+let options = {
+  getLocation(source) {
+    const query = new URLSearchParams(
+      source.location.search
+    )
+
+    return {
+      ...source.location,
+      query,
+      state: source.history.state,
+      key:
+        (source.history.state &&
+          source.history.state.key) ||
+        "initial"
+    }
+  }
+}
+
+// listen to the browser history
+let history = createHistory(window, options)
+```