Location descriptors in createPath and createHref

CHANGES.md

@@ -1,3 +1,12 @@
+## [HEAD]
+> Unreleased
+
+- **Feature** Accept location descriptors in `createPath` and `createHref` ([#173])
+- **Deprecation** Deprecate the `query` arg to `createPath` and `createHref` in favor of using location descriptor objects ([#173])
+
+[HEAD]: https://github.com/rackt/history/compare/latest...HEAD
+[#173]: https://github.com/rackt/history/pull/173
+
 ## [v1.14.0]
 > Dec 6, 2015
 

docs/Glossary.md

@@ -70,8 +70,8 @@ A *hash* is a string that represents the hash portion of the URL. It is synonymo
       goBack() => void;
       goForward() => void;
       createKey() => LocationKey;
-      createPath(path: Path) => Path;
-      createHref(path: Path) => Href;
+      createPath(location: LocationDescriptor) => Path;
+      createHref(location: LocationDescriptor) => Href;
     };
 
 ### HistoryOptions

docs/QuerySupport.md

@@ -25,9 +25,9 @@ const history = useQueries(createHistory)({
 })
 ```
 
-Query-enhanced histories accept URL queries as trailing arguments to `createPath`, and `createHref`, and accept `query` as a key for `push` and `replace`.
+Query-enhanced histories accept URL queries as the `query` key for `push`, `replace`, `createPath`, and `createHref`.
 
 ```js
-history.createPath('/the/path', { the: 'query' })
+history.createPath({ pathname: '/the/path', query: { the: 'query' } })
 history.push({ pathname: '/the/path', query: { the: 'query' } })
 ```

modules/__tests__/describeQueries.js

@@ -156,35 +156,64 @@ function describeQueries(createHistory) {
     describe('in createPath', function () {
       it('works', function () {
         expect(
-          history.createPath('/the/path', { the: 'query value' })
+          history.createPath({
+            pathname: '/the/path',
+            query: { the: 'query value' }
+          })
         ).toEqual('/the/path?the=query+value')
       })
 
       it('does not strip trailing slash', function () {
         expect(
-          history.createPath('/the/path/', { the: 'query value' })
+          history.createPath({
+            pathname: '/the/path/',
+            query: { the: 'query value' }
+          })
         ).toEqual('/the/path/?the=query+value')
       })
 
+      it('works with deprecated query arg', function () {
+        expect(
+          history.createPath('/the/path', { the: 'query value' })
+        ).toEqual('/the/path?the=query+value')
+      })
+
       describe('when the path contains a hash', function () {
         it('puts the query before the hash', function () {
           expect(
-            history.createPath('/the/path#the-hash', { the: 'query value' })
+            history.createPath({
+              pathname: '/the/path',
+              hash: '#the-hash',
+              query: { the: 'query value' }
+            })
           ).toEqual('/the/path?the=query+value#the-hash')
         })
       })
 
       describe('when there is already an existing search', function () {
         it('preserves the existing search', function () {
           expect(
-            history.createPath('/the/path?a=one', { the: 'query value' })
+            history.createPath({
+              pathname: '/the/path',
+              search: '?a=one',
+              query: { the: 'query value' }
+            })
           ).toEqual('/the/path?a=one&the=query+value')
         })
       })
     })
 
     describe('in createHref', function () {
       it('works', function () {
+        expect(
+          stripHash(history.createHref({
+            pathname: '/the/path',
+            query: { the: 'query value' }
+          }))
+        ).toEqual('/the/path?the=query+value')
+      })
+
+      it('works with deprecated query arg', function () {
         expect(
           stripHash(history.createHref('/the/path', { the: 'query value' }))
         ).toEqual('/the/path?the=query+value')
@@ -321,28 +350,42 @@ function describeQueries(createHistory) {
     describe('in createPath', function () {
       it('works', function () {
         expect(
-          history.createPath('/the/path', { the: 'query' })
+          history.createPath({
+            pathname: '/the/path',
+            query: { the: 'query' }
+          })
         ).toEqual('/the/path?STRINGIFY_QUERY')
       })
 
       it('does not strip trailing slash', function () {
         expect(
-          history.createPath('/the/path/', { the: 'query' })
+          history.createPath({
+            pathname: '/the/path/',
+            query: { the: 'query' }
+          })
         ).toEqual('/the/path/?STRINGIFY_QUERY')
       })
 
       describe('when the path contains a hash', function () {
         it('puts the query before the hash', function () {
           expect(
-            history.createPath('/the/path#the-hash', { the: 'query' })
+            history.createPath({
+              pathname: '/the/path',
+              hash: '#the-hash',
+              query: { the: 'query' }
+            })
           ).toEqual('/the/path?STRINGIFY_QUERY#the-hash')
         })
       })
 
       describe('when there is already an existing search', function () {
         it('preserves the existing search', function () {
           expect(
-            history.createPath('/the/path?a=one', { the: 'query' })
+            history.createPath({
+              pathname: '/the/path',
+              search: '?a=one',
+              query: { the: 'query' }
+            })
           ).toEqual('/the/path?a=one&STRINGIFY_QUERY')
         })
       })
@@ -351,7 +394,10 @@ function describeQueries(createHistory) {
     describe('in createHref', function () {
       it('works', function () {
         expect(
-          stripHash(history.createHref('/the/path', { the: 'query' }))
+          stripHash(history.createHref({
+            pathname: '/the/path',
+            query: { the: 'query' }
+          }))
         ).toEqual('/the/path?STRINGIFY_QUERY')
       })
     })

modules/createHistory.js

@@ -160,11 +160,11 @@ function createHistory(options={}) {
     return createRandomKey(keyLength)
   }
 
-  function createPath(path) {
-    if (path == null || typeof path === 'string')
-      return path
+  function createPath(location) {
+    if (location == null || typeof location === 'string')
+      return location
 
-    const { pathname, search, hash } = path
+    const { pathname, search, hash } = location
 
     let result = pathname
 
@@ -177,8 +177,8 @@ function createHistory(options={}) {
     return result
   }
 
-  function createHref(path) {
-    return createPath(path)
+  function createHref(location) {
+    return createPath(location)
   }
 
   function createLocation(path, state, action, key=createKey()) {

modules/useBasename.js

@@ -74,12 +74,12 @@ function useBasename(createHistory) {
       history.replace(prependBasename(location))
     }
 
-    function createPath(path) {
-      return history.createPath(prependBasename(path))
+    function createPath(location) {
+      return history.createPath(prependBasename(location))
     }
 
-    function createHref(path) {
-      return history.createHref(prependBasename(path))
+    function createHref(location) {
+      return history.createHref(prependBasename(location))
     }
 
     function createLocation() {

modules/useQueries.js

@@ -104,12 +104,20 @@ function useQueries(createHistory) {
       history.replace(appendQuery(location, location.query))
     }
 
-    function createPath(path, query) {
-      return history.createPath(appendQuery(path, query))
+    function createPath(location, query) {
+      warning(
+        query,
+        'the query argument to createPath is deprecated; use a location descriptor instead'
+      )
+      return history.createPath(appendQuery(location, query || location.query))
     }
 
-    function createHref(path, query) {
-      return history.createHref(appendQuery(path, query))
+    function createHref(location, query) {
+      warning(
+        query,
+        'the query argument to createHref is deprecated; use a location descriptor instead'
+      )
+      return history.createHref(appendQuery(location, query || location.query))
     }
 
     function createLocation() {