Document the new push and replace syntax

remix-run · Dec 6, 2015 · 50420f9 · 50420f9
1 parent 0a1b31a
commit 50420f9
Show file tree

Hide file tree

Showing 5 changed files with 54 additions and 9 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,5 +1,8 @@
 ## [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]) 
@@ -9,6 +12,7 @@
 - Use query-string module instead of qs to save on bytes ([#121])
 
 [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

diff --git a/docs/GettingStarted.md b/docs/GettingStarted.md
@@ -28,17 +28,16 @@ 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()`
 
-There are also two handy methods that allow you not to specify `state` object during transitions:
+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.
 
-- `push(path[, state])`
-- `replace(path[, state])`
-
-The [`path`](Glossary.md#path) argument to `pushState`, `push`, `replaceState` and `replace` 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 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.
 
 ```js
 // Push a new entry onto the history stack.
@@ -47,9 +46,15 @@ history.pushState({ some: 'state' }, '/home')
 // Replace the current entry on the history stack.
 history.replaceState({ some: 'other state' }, '/profile')
 
-// Push a new history entry, omitting `state` object (it will be set to `null`)
+// Push a path with null state.
 history.push('/about')
 
+// Push a new history location object with state.
+history.push({ pathname: '/contact', state: { some: 'state' } })
+
+// Change just the search on an existing location.
+history.push({ ...location, search: '?the=search' })
+
 // Go back to the previous history entry. The following
 // two lines are synonymous.
 history.go(-1)

diff --git a/docs/Glossary.md b/docs/Glossary.md
@@ -11,6 +11,7 @@ This is a glossary of common terms used in the history codebase and documentatio
 * [HistoryOptions](#historyoptions)
 * [Href](#href)
 * [Location](#location)
+* [LocationDescriptor](#locationdescriptor)
 * [LocationKey](#locationkey)
 * [LocationListener](#locationlistener)
 * [LocationState](#locationstate)
@@ -64,9 +65,9 @@ A *hash* is a string that represents the hash portion of the URL. It is synonymo
       listen: (listener: LocationListener) => Function;
       transitionTo(location: Location) => void;
       pushState(state: LocationState, path: Path) => void;
-      push(path: Path) => void;
+      push(location: LocationDescriptor) => void;
       replaceState(state: LocationState, path: Path) => void;
-      replace(path: Path) => void;
+      replace(location: LocationDescriptor) => void;
       go(n: number) => void;
       goBack() => void;
       goForward() => void;
@@ -105,6 +106,23 @@ A *location* answers two important (philosophical) questions:
 
 New locations are typically created each time the URL changes. You can read more about locations in [the `history` docs](https://github.com/rackt/history/blob/master/docs/Location.md).
 
+### LocationDescriptor
+
+    type LocationDescriptorObject = {
+      pathname: Pathname;
+      search: Search;
+      query: Query;
+      state: LocationState;
+    };
+
+    type LocationDescriptor = LocationDescriptorObject | Path;
+
+A *location descriptor* is the pushable analogue of a location. The `history` object uses `location`s to tell its listeners where they _are_, while history users use location descriptors to tell the `history` object where to _go_.
+
+The object signature is compatible with that of `location`, differing only in ignoring the internally-generated `action` and `key` fields. This allows you to build a location descriptor from an existing `location`, which can be used to change only specific fields on the `location`.
+
+For convenience, you can always use path strings instead of objects wherever a location descriptor is expected.
+
 ### LocationKey
 
     type LocationKey = string;

diff --git a/docs/Location.md b/docs/Location.md
@@ -12,6 +12,23 @@ key           A unique identifier for this location
 
 Support for query string parsing is provided using the [`useQueries` module](QuerySupport.md).
 
+### Location Descriptors
+
+[Location descriptors](Glossary.md#locationdescriptor) can be either objects or path strings. As objects, they are like `location` objects, except they ignore the internally-generated `action` and `key` fields.
+
+You can use location descriptors to call `history.push` and `history.replace`. Location descriptor objects can define just the portions of the next `location` that you want to set. They can also extend an existing `location` object to change only specific fields on that `location`.
+
+```js
+// Pushing a path string.
+history.push('/the/path')
+
+// Omitting location state when pushing a location descriptor.
+history.push({ pathname: '/the/path', search: '?the=search' })
+
+// Extending an existing location object.
+history.push({ ...location, search: '?other=search' })
+```
+
 ### Programmatic Creation
 
 You may occasionally need to create a `location` object, either for testing or when using `history` in a stateless, non-DOM environment (i.e. a server). In these cases, you can use the `createLocation` method directly:

diff --git a/docs/QuerySupport.md b/docs/QuerySupport.md
@@ -25,9 +25,10 @@ const history = useQueries(createHistory)({
 })
 ```
 
-Query-enhanced histories also accept URL queries as trailing arguments to `pushState`, `replaceState`, `createPath`, and `createHref`.
+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`.
 
 ```js
 history.createPath('/the/path', { the: 'query' })
 history.pushState(null, '/the/path', { the: 'query' })
+history.push({ pathname: '/the/path', query: { the: 'query' } })
 ```