[wip] Deprecate pushState and replaceState

CHANGES.md

@@ -1,20 +1,17 @@
 ## [HEAD]
 
-#### New features
-- Accept objects in `history.push` and `history.replace` ([#141])
-
-#### Bug fixes
-- Disable browser history on Chrome iOS ([#146])
-- Do not convert same-path PUSH to REPLACE if the hash has changed ([#167]) 
-
-#### Other
-- Add ES2015 module build ([#152])
+- **Feature:** Accept objects in `history.push` and `history.replace` ([#141])
+- **Deprecation:** Deprecate `history.pushState` and `history.replaceState` in favor of passing objects to `history.push` and `history.replace` ([#168])
+- **Bugfix:** Disable browser history on Chrome iOS ([#146])
+- **Bugfix:** Do not convert same-path PUSH to REPLACE if the hash has changed ([#167]) 
+- **Other:** Add ES2015 module build ([#152])
 
 [HEAD]: https://github.com/rackt/history/compare/latest...HEAD
 [#141]: https://github.com/rackt/history/pull/141
 [#146]: https://github.com/rackt/history/pull/146
 [#152]: https://github.com/rackt/history/pull/152
 [#167]: https://github.com/rackt/history/pull/167
+[#167]: https://github.com/rackt/history/pull/168
 
 ## [v1.13.1]
 > Nov 13, 2015

docs/BasenameSupport.md

@@ -17,11 +17,10 @@ history.listen(function (location) {
 })
 ```
 
-Basename-enhanced histories also automatically prepend the basename to paths used in `pushState`, `push`, `replaceState`, `replace`, `createPath`, and `createHref`.
+Basename-enhanced histories also automatically prepend the basename to paths used in `push`, `replace`, `createPath`, and `createHref`.
 
 ```js
 history.createPath('/the/path') // /base/the/path
-history.pushState(null, '/the/path') // push /base/the/path
 history.push('/the/path') // push /base/the/path
 ```
 

docs/GettingStarted.md

@@ -27,33 +27,32 @@ unlisten()
 
 You can also use a `history` object to programmatically change the current `location` using the following methods:
 
-- `pushState(state, path)`
 - `push(location)`
-- `replaceState(state, path)`
 - `replace(location)`
 - `go(n)`
 - `goBack()`
 - `goForward()`
 
-The [`path`](Glossary.md#path) argument to `pushState` and `replaceState` represents a complete URL path, including the [search string](Glossary.md#search) and [hash](Glossary.md#hash). The [`state`](Glossary.md#locationstate) argument should be a JSON-serializable object.
+The `push` and `replace` methods take a [path string](Glossary.md#path) that represents a complete URL path, including the [search string](Glossary.md#search) and [hash](Glossary.md#hash).
 
-The location argument to `push` and `replace` can be either a path string as above or a [location descriptor](Glossary.md#locationdescriptor) object representing the next history entry, including the state.
+They can also accept a [location descriptor](Glossary.md#locationdescriptor) object that defines the path as a combination of [`pathname`](Glossary.md#pathname), [`search`](Glossary.md#search), and [`hash`](Glossary.md#hash). This object can also include [`state`](Glossary.md#locationstate) as a JSON-serializable object.
 
 ```js
 // Push a new entry onto the history stack.
-history.pushState({ some: 'state' }, '/home')
+history.push('/home')
 
 // Replace the current entry on the history stack.
-history.replaceState({ some: 'other state' }, '/profile')
+history.replace('/profile')
 
-// Push a path with null state.
-history.push('/about')
-
-// Push a new history location object with state.
-history.push({ pathname: '/contact', state: { some: 'state' } })
+// Push a new entry with state onto the history stack.
+history.push({
+  pathname: '/about',
+  search: '?the=search',
+  state: { some: 'state' }
+})
 
 // Change just the search on an existing location.
-history.push({ ...location, search: '?the=search' })
+history.push({ ...location, search: '?the=other+search' })
 
 // Go back to the previous history entry. The following
 // two lines are synonymous.

docs/Glossary.md

@@ -64,9 +64,7 @@ A *hash* is a string that represents the hash portion of the URL. It is synonymo
       listenBefore: (hook: TransitionHook) => Function;
       listen: (listener: LocationListener) => Function;
       transitionTo(location: Location) => void;
-      pushState(state: LocationState, path: Path) => void;
       push(location: LocationDescriptor) => void;
-      replaceState(state: LocationState, path: Path) => void;
       replace(location: LocationDescriptor) => void;
       go(n: number) => void;
       goBack() => void;

docs/QuerySupport.md

@@ -23,10 +23,9 @@ history.listen(function (location) {
 })
 ```
 
-Query-enhanced histories accept URL queries as trailing arguments to `pushState`, `replaceState`, `createPath`, and `createHref`, and accept `query` as a key for `push` and `replace`.
+Query-enhanced histories accept URL queries as trailing arguments to `createPath`, and `createHref`, and accept `query` as a key for `push` and `replace`.
 
 ```js
 history.createPath('/the/path', { the: 'query' })
-history.pushState(null, '/the/path', { the: 'query' })
 history.push({ pathname: '/the/path', query: { the: 'query' } })
 ```

modules/createHashHistory.js

@@ -156,24 +156,6 @@ function createHashHistory(options={}) {
     }
   }
 
-  function pushState(state, path) {
-    warning(
-      queryKey || state == null,
-      'You cannot use state without a queryKey it will be dropped'
-    )
-
-    history.pushState(state, path)
-  }
-
-  function replaceState(state, path) {
-    warning(
-      queryKey || state == null,
-      'You cannot use state without a queryKey it will be dropped'
-    )
-
-    history.replaceState(state, path)
-  }
-
   let goIsSupportedWithoutReload = supportsGoWithoutReloadUsingHash()
 
   function go(n) {
@@ -205,6 +187,26 @@ function createHashHistory(options={}) {
       stopHashChangeListener()
   }
 
+  // deprecated - warning is in createHistory
+  function pushState(state, path) {
+    warning(
+      queryKey || state == null,
+      'You cannot use state without a queryKey it will be dropped'
+    )
+
+    history.pushState(state, path)
+  }
+
+  // deprecated - warning is in createHistory
+  function replaceState(state, path) {
+    warning(
+      queryKey || state == null,
+      'You cannot use state without a queryKey it will be dropped'
+    )
+
+    history.replaceState(state, path)
+  }
+
   return {
     ...history,
     listenBefore,

modules/createHistory.js

@@ -136,26 +136,12 @@ function createHistory(options={}) {
     })
   }
 
-  function pushState(state, path) {
-    if (typeof path === 'string')
-      path = parsePath(path)
-
-    push({ state, ...path })
-  }
-
   function push(location) {
     transitionTo(
       createLocation(location, null, PUSH, createKey())
     )
   }
 
-  function replaceState(state, path) {
-    if (typeof path === 'string')
-      path = parsePath(path)
-
-    replace({ state, ...path })
-  }
-
   function replace(location) {
     transitionTo(
       createLocation(location, null, REPLACE, createKey())
@@ -225,12 +211,26 @@ function createHistory(options={}) {
     transitionHooks = transitionHooks.filter(item => item !== hook)
   }
 
+  // deprecated
+  function pushState(state, path) {
+    if (typeof path === 'string')
+      path = parsePath(path)
+
+    push({ state, ...path })
+  }
+
+  // deprecated
+  function replaceState(state, path) {
+    if (typeof path === 'string')
+      path = parsePath(path)
+
+    replace({ state, ...path })
+  }
+
   return {
     listenBefore,
     listen,
     transitionTo,
-    pushState,
-    replaceState,
     push,
     replace,
     go,
@@ -252,6 +252,14 @@ function createHistory(options={}) {
     unregisterTransitionHook: deprecate(
       unregisterTransitionHook,
       'unregisterTransitionHook is deprecated; use the callback returned from listenBefore instead'
+    ),
+    pushState: deprecate(
+      pushState,
+      'pushState is deprecated; use push instead'
+    ),
+    replaceState: deprecate(
+      replaceState,
+      'replaceState is deprecated; use replace instead'
     )
   }
 }

modules/useBasename.js

@@ -2,6 +2,7 @@ import { canUseDOM } from './ExecutionEnvironment'
 import runTransitionHook from './runTransitionHook'
 import extractPath from './extractPath'
 import parsePath from './parsePath'
+import deprecate from './deprecate'
 
 function useBasename(createHistory) {
   return function (options={}) {
@@ -65,24 +66,10 @@ function useBasename(createHistory) {
     }
 
     // Override all write methods with basename-aware versions.
-    function pushState(state, path) {
-      if (typeof path === 'string')
-        path = parsePath(path)
-
-      push({ state, ...path })
-    }
-
     function push(location) {
       history.push(prependBasename(location))
     }
 
-    function replaceState(state, path) {
-      if (typeof path === 'string')
-        path = parsePath(path)
-
-      replace({ state, ...path })
-    }
-
     function replace(location) {
       history.replace(prependBasename(location))
     }
@@ -99,17 +86,40 @@ function useBasename(createHistory) {
       return addBasename(history.createLocation.apply(history, arguments))
     }
 
+    // deprecated
+    function pushState(state, path) {
+      if (typeof path === 'string')
+        path = parsePath(path)
+
+      push({ state, ...path })
+    }
+
+    // deprecated
+    function replaceState(state, path) {
+      if (typeof path === 'string')
+        path = parsePath(path)
+
+      replace({ state, ...path })
+    }
+
     return {
       ...history,
       listenBefore,
       listen,
-      pushState,
       push,
-      replaceState,
       replace,
       createPath,
       createHref,
-      createLocation
+      createLocation,
+
+      pushState: deprecate(
+        pushState,
+        'pushState is deprecated; use push instead'
+      ),
+      replaceState: deprecate(
+        replaceState,
+        'replaceState is deprecated; use replace instead'
+      )
     }
   }
 }

modules/useQueries.js

@@ -1,6 +1,7 @@
 import qs from 'qs'
 import runTransitionHook from './runTransitionHook'
 import parsePath from './parsePath'
+import deprecate from './deprecate'
 
 const SEARCH_BASE_KEY = '$searchBase'
 
@@ -79,24 +80,10 @@ function useQueries(createHistory) {
     }
 
     // Override all write methods with query-aware versions.
-    function pushState(state, path, query) {
-      if (typeof path === 'string')
-        path = parsePath(path)
-
-      push({ state, ...path, query })
-    }
-
     function push(location) {
       history.push(appendQuery(location, location.query))
     }
 
-    function replaceState(state, path, query) {
-      if (typeof path === 'string')
-        path = parsePath(path)
-
-      replace({ state, ...path, query })
-    }
-
     function replace(location) {
       history.replace(appendQuery(location, location.query))
     }
@@ -113,17 +100,40 @@ function useQueries(createHistory) {
       return addQuery(history.createLocation.apply(history, arguments))
     }
 
+    // deprecated
+    function pushState(state, path, query) {
+      if (typeof path === 'string')
+        path = parsePath(path)
+
+      push({ state, ...path, query })
+    }
+
+    // deprecated
+    function replaceState(state, path, query) {
+      if (typeof path === 'string')
+        path = parsePath(path)
+
+      replace({ state, ...path, query })
+    }
+
     return {
       ...history,
       listenBefore,
       listen,
-      pushState,
       push,
-      replaceState,
       replace,
       createPath,
       createHref,
-      createLocation
+      createLocation,
+
+      pushState: deprecate(
+        pushState,
+        'pushState is deprecated; use push instead'
+      ),
+      replaceState: deprecate(
+        replaceState,
+        'replaceState is deprecated; use replace instead'
+      )
     }
   }
 }