space-router 0.8.2 → 0.8.5

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.8.5
+
+- fix redirects - the history was not ready by the time initial transition was kicked off by redirecting
+- remove the possibility to pass the current route via the `merge` option directly, instead set `merge: true` (truthy value works now), and instead optionally pass the current route as the second argument to `navigate(to, curr)` or `href(to, curr)`, this is a breaking change, but also an undocumented API as it it's still being refined and is used for correctly merging urls during async navigations.
+
+## 0.8.4
+
+- fix the `navigate(url: string)` implementation where `"".replace` was being tested instead of `to.replace`
+
+## 0.8.3
+
+- re-introduce `navigate(url: string)` since it's nice and convenient
+
 ## 0.8.2
 
 - refer to `setImmediate` via `global.setImmediate` to fix a webpack compilation error

package/dist/cjs/history.js

@@ -3,10 +3,11 @@
 exports.__esModule = true;
 exports.createHistory = createHistory;
 
-function createHistory(onChange, options) {
+function createHistory(options) {
   var sync = options.sync;
   var mode = options.mode;
   var raf;
+  var onPop;
   var memory = [];
   var off;
   var destroyed = false;
@@ -26,29 +27,30 @@ function createHistory(onChange, options) {
     }
   }
 
-  if (mode !== 'memory') {
-    off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onPop);
-  }
+  function listen(onChange) {
+    onPop = function onPop() {
+      return onChange(getUrl());
+    };
 
-  function onPop() {
-    onChange(getUrl());
-  }
+    if (mode !== 'memory') {
+      off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onPop);
+      raf(onPop);
+    }
 
-  if (mode !== 'memory') {
-    onChange(getUrl());
+    return function () {
+      destroyed = true;
+      off && off();
+    };
   }
 
   return {
+    listen: listen,
     getUrl: getUrl,
     push: function push(url) {
       go(url);
     },
     replace: function replace(url) {
       go(url, true);
-    },
-    destroy: function destroy() {
-      destroyed = true;
-      off && off();
     }
   };
 

package/dist/cjs/router.js

@@ -40,42 +40,47 @@ function createRouter(options) {
       }
 
       routes = flatten(routeMap);
-
-      var onHistoryChange = function onHistoryChange(url) {
-        return transition(router, url, cb);
-      };
-
-      history = (0, _history.createHistory)(onHistoryChange, {
+      history = (0, _history.createHistory)({
         mode: mode,
         sync: sync
       });
+      var dispose = history.listen(function (url) {
+        return transition(router, url, cb);
+      });
       return function () {
-        history.destroy();
+        dispose();
         history = null;
         routes = [];
       };
     },
-    navigate: function navigate(to) {
-      var url;
-      var replace = false;
-
-      if (to.url) {
-        url = to.url;
-      } else {
-        url = router.href(to);
+    navigate: function navigate(to, curr) {
+      if (typeof to === 'string') {
+        to = {
+          url: to
+        };
       }
 
-      replace = !!to.replace;
+      var url = router.href(to, curr);
 
-      if (replace) {
+      if (to.replace) {
         history.replace(url);
       } else {
         history.push(url);
       }
     },
-    href: function href(to) {
+    href: function href(to, curr) {
+      // already a url
+      if (typeof to === 'string') {
+        return to;
+      } // align with navigate API
+
+
+      if (to.url) {
+        return to.url;
+      }
+
       if (to.merge) {
-        var curr = to.merge === true ? router.match(router.getUrl()) : to.merge;
+        curr = curr || router.match(router.getUrl());
         to = merge(curr, to);
       }
 
@@ -172,7 +177,7 @@ function redirectUrl(router, redirect, matchingRoute) {
     redirect = redirect(matchingRoute);
   }
 
-  return redirect.url ? redirect.url : router.href(redirect);
+  return router.href(redirect);
 }
 
 function data(routes, matchingRoute) {
@@ -188,7 +193,7 @@ function merge(curr, to) {
     curr = {};
   }
 
-  var pathname = to.pathname || curr.pattern;
+  var pathname = to.pathname || curr.pattern || curr.pathname;
   var params = Object.assign({}, curr.params, to.params);
   var query = to.query === null ? null : Object.assign({}, curr.query, to.query);
   var hash = to.hash === null ? null : to.hash || curr.hash || '';

package/dist/esm/history.js

@@ -1,7 +1,8 @@
-export function createHistory(onChange, options) {
+export function createHistory(options) {
   const sync = options.sync;
   let mode = options.mode;
   let raf;
+  let onPop;
   const memory = [];
   let off;
   let destroyed = false;
@@ -17,19 +18,22 @@ export function createHistory(onChange, options) {
     }
   }
 
-  if (mode !== 'memory') {
-    off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onPop);
-  }
+  function listen(onChange) {
+    onPop = () => onChange(getUrl());
 
-  function onPop() {
-    onChange(getUrl());
-  }
+    if (mode !== 'memory') {
+      off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onPop);
+      raf(onPop);
+    }
 
-  if (mode !== 'memory') {
-    onChange(getUrl());
+    return () => {
+      destroyed = true;
+      off && off();
+    };
   }
 
   return {
+    listen,
     getUrl,
 
     push(url) {
@@ -38,11 +42,6 @@ export function createHistory(onChange, options) {
 
     replace(url) {
       go(url, true);
-    },
-
-    destroy() {
-      destroyed = true;
-      off && off();
     }
 
   };

package/dist/esm/router.js

@@ -14,42 +14,47 @@ export function createRouter(options = {}) {
       }
 
       routes = flatten(routeMap);
-
-      const onHistoryChange = url => transition(router, url, cb);
-
-      history = createHistory(onHistoryChange, {
+      history = createHistory({
         mode,
         sync
       });
+      const dispose = history.listen(url => transition(router, url, cb));
       return () => {
-        history.destroy();
+        dispose();
         history = null;
         routes = [];
       };
     },
 
-    navigate(to) {
-      let url;
-      let replace = false;
-
-      if (to.url) {
-        url = to.url;
-      } else {
-        url = router.href(to);
+    navigate(to, curr) {
+      if (typeof to === 'string') {
+        to = {
+          url: to
+        };
       }
 
-      replace = !!to.replace;
+      const url = router.href(to, curr);
 
-      if (replace) {
+      if (to.replace) {
         history.replace(url);
       } else {
         history.push(url);
       }
     },
 
-    href(to) {
+    href(to, curr) {
+      // already a url
+      if (typeof to === 'string') {
+        return to;
+      } // align with navigate API
+
+
+      if (to.url) {
+        return to.url;
+      }
+
       if (to.merge) {
-        const curr = to.merge === true ? router.match(router.getUrl()) : to.merge;
+        curr = curr || router.match(router.getUrl());
         to = merge(curr, to);
       }
 
@@ -145,7 +150,7 @@ function redirectUrl(router, redirect, matchingRoute) {
     redirect = redirect(matchingRoute);
   }
 
-  return redirect.url ? redirect.url : router.href(redirect);
+  return router.href(redirect);
 }
 
 function data(routes, matchingRoute) {
@@ -157,7 +162,7 @@ function data(routes, matchingRoute) {
 }
 
 export function merge(curr = {}, to) {
-  const pathname = to.pathname || curr.pattern;
+  const pathname = to.pathname || curr.pattern || curr.pathname;
   const params = Object.assign({}, curr.params, to.params);
   const query = to.query === null ? null : Object.assign({}, curr.query, to.query);
   const hash = to.hash === null ? null : to.hash || curr.hash || '';

package/docs/assets/styles/main.scss

@@ -204,6 +204,7 @@ h1 {
 
 #TOC {
   padding: 32px;
+  margin-top: 24px;
 
   @media (min-width: 768px) {
     color: rgb(26, 26, 26);
@@ -231,8 +232,9 @@ h1 {
   margin: 0;
   list-style: none;
 }
-#TOC ul > ul {
+#TOC ul ul {
   margin: 0;
+  margin-top: 12px;
 }
 #TOC ul {
   list-style: none;
@@ -259,7 +261,8 @@ h1 {
 }
 
 #TOC > nav > ul > li > a {
-  font-weight: bold;
+  font-size: 20px;
+  font-weight: 500;
   margin-top: 12px;
 }
 

package/docs/content/_index.md

@@ -59,8 +59,8 @@ const routes = [
 // create the router
 const router = createRouter()
 
-// start listening to the URL changes and kick of the initial render
-// based on the current URL
+// start listening to the url changes and kick of the initial render
+// based on the current url
 export const dispose = router.listen(routes, render)
 
 // every time the route changes, do something, e.g. re-render your app
@@ -86,7 +86,7 @@ function render(route) {
 const router = createRouter(options)
 ```
 
-Creates the router object.
+Create the router object.
 
 - `options` object
   - `mode` - one of `history`, `hash`, `memory`, default is `history`
@@ -98,18 +98,27 @@ Creates the router object.
 const dispose = router.listen(routes, onChange)
 ```
 
-Starts listening to url changes. Every time the url changes via back/forward button or by performing programmatic navigations, the `onChange` callback will get called with the matched `route` object.
+Start listening to url changes. Every time the url changes via back/forward button or by performing programmatic navigations, the `onChange` callback will get called with the matched `route` object.
 
-Note, calling listen will immediately call `onChange` based on the current URL when in `history` or `hash` modes. This does not happen in `memory` mode so that you could perform the initial navigation yourself since there is no URL to read from in that case.
+Note, calling listen will immediately call `onChange` based on the current url when in `history` or `hash` modes. This does not happen in `memory` mode so that you could perform the initial navigation yourself since there is no url to read from in that case.
 
 - `routes` an array of arrays of route definitions, where each route is an object of shape `{ path, redirect, routes, ...metadata }`
-  - `path` is the URL pattern to match that can include named parameters as segments
+  - `path` is the url pattern to match that can include named parameters as segments
   - `redirect` can be a string or a function that redirects upon entering that route
   - `routes` is a nested object of nested route definitions
   - `...metadata` all other other keys can be chosen by you
-- `onChange` is called with `(route)`
-  - `route` is an object of shape `{ pattern, href, pathname, params, query, search, hash }`
-  - `data` is an array of datas associated with this route
+- `onChange` is called with the `route` object
+
+`route` is an object of shape `{ url, pathname, params, query, search, hash, pattern, data }`:
+
+- `url` full relative url string including query string and hash if any
+- `pathname` the pathname portion of the target url, which can include named segments
+- `params` params extracted from the named pathname segments
+- `query` query object that was parsed with `qs.parse`
+- `search` full unparsed query string
+- `hash` hash fragment
+- `pattern` the matched route pattern as defined in the route config
+- `data` an array of nested matched route objects with any metadata found in the route config
 
 Listen returns a `dispose` function that stops listening to url changes.
 
@@ -117,22 +126,30 @@ Listen returns a `dispose` function that stops listening to url changes.
 
 ```js
 router.navigate(to)
+
+// examples
+router.navigate('/shows')
+router.navigate({ url: '/show/1' })
+router.navigate({ url: '/show/2', replace: true })
+router.navigate({ pathname: '/shows', query: { 'most-recent': 1 } })
+router.navigate({ query: { 'top-rated': 1 }, merge: true })
+router.navigate({ query: { 'top-rated': undefined }, merge: true })
 ```
 
-Navigates to a URL described.
+Navigate to a url. Navigating will update the browser's location bar (unless in `memory` mode) and will call the router listener callback with the newly matched route.
 
-- `to` - navigation target
+- `to` - a `string` url or an `object` with the following properties
   - `url` a relative url string or a route pattern
   - `pathname` the pathname portion of the target url, which can include named segments
   - `params` params to interpolate into the named pathname segments
   - `query` the query object that will be passed through `qs.stringify`
   - `hash` the hash fragment to append to the url of the url
   - `replace` set to true to replace the current entry in the navigation stack instead of pushing
-  - `merge` set to true to merge in the params from the current URL, alternatively set to the current route object to use that as the current route to be used in merging
+  - `merge` set to true to merge in the params from the current url, alternatively set to the current route object to use that as the current route to be used in merging
 
 Note, if `url` option is provided, the `pathname`, `params`, `query` and `hash` will be ignored.
 
-Note, be careful when using `merge` as this reads the location's current URL which might be different from the one you store in your application's state in case you're performing async logic in the listen callback.
+Note, be careful when using `merge` as this reads the location's current url which might be different from the one you store in your application's state in case you're performing async logic in the listen callback.
 
 ### `match`
 
@@ -140,24 +157,33 @@ Note, be careful when using `merge` as this reads the location's current URL whi
 const route = router.match(url)
 ```
 
-Match the url against the routes and return the matching route object. Useful in server side rendering to translate the request URL to a matching route.
+Match the url string against the routes and return the matching route object.
 
 ### `href`
 
 ```js
 const url = router.href(to)
+
+// examples
+router.href('/shows')
+router.href({ url: '/show/1' })
+router.href({ pathname: '/shows', query: { 'most-recent': 1 } })
+router.href({ query: { 'top-rated': 1 }, merge: true })
+router.href({ query: { 'top-rated': undefined }, merge: true })
 ```
 
-Create a relative URL string to use in `<a href>` attribute.
+Create a relative url string to use in `<a href>` attribute.
 
 - `to` object of shape `{ pathname, params, query, hash }`. The `params` will be interpolated into the pathname if the pathname contains any parametrised segments. The `query` is an object that will be passed through `qs.stringify`.
 
+Note: `to` can be a string, in which case `href` simply returns the input. Similarly, the to can contain `{ url }` key in which case `href` returns that url. This is to align the function signature with that of `navigate` so the two can be used interchangeably.
+
 ### `getUrl`
 
 ```js
 const url = router.getUrl()
 ```
 
-Get the current URL string. Note, this only includes the path and does not not include the protocol and host.
+Get the current url string. Note, this only includes the path and does not not include the protocol and host.
 
-You shouldn't need to read this most of the time since the updates to URL changes and the matching route will be provided in the `listen` callback. Be especially careful if you're performing asynchronous logic in your callback, such as lazily importing some modules, where you're then constructing links based on the current url - use route provided to your listener instead of calling `getUrl` as the URL might already have been updated to another value in the meantime.
+You shouldn't need to read this most of the time since the updates to url changes and the matching route will be provided in the `listen` callback. Be especially careful if you're performing asynchronous logic in your callback, such as lazily importing some modules, where you're then constructing links based on the current url - use route provided to your listener instead of calling `getUrl` as the url might already have been updated to another value in the meantime.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "space-router",
   "description": "All the routing essentials.",
-  "version": "0.8.2",
+  "version": "0.8.5",
   "main": "dist/cjs",
   "module": "dist/esm",
   "license": "ICS",
@@ -27,21 +27,21 @@
     "build": "node ./tasks/build.js",
     "watch": "node ./tasks/build.js -w",
     "version": "npm run build",
-    "release": "np",
-    "release:beta": "np --tag=beta",
+    "release": "np --no-release-draft",
+    "release:beta": "np --tag=beta --no-release-draft",
     "release:docs": "hugo -s docs && gh-pages -d docs/public"
   },
   "devDependencies": {
-    "@babel/cli": "^7.16.0",
-    "@babel/preset-env": "^7.16.0",
+    "@babel/cli": "^7.17.6",
+    "@babel/preset-env": "^7.16.11",
     "ava": "^3.15.0",
     "esm": "^3.2.25",
     "execa": "^5.1.1",
     "gh-pages": "^3.2.3",
-    "healthier": "^4.0.0",
-    "np": "^7.5.0",
+    "healthier": "^5.0.1",
+    "np": "^7.6.1",
     "nyc": "^15.1.0",
-    "prettier": "^2.4.1"
+    "prettier": "^2.6.2"
   },
   "healthier": {
     "global": [

package/src/history.js

@@ -1,7 +1,8 @@
-export function createHistory(onChange, options) {
+export function createHistory(options) {
   const sync = options.sync
   let mode = options.mode
   let raf
+  let onPop
 
   const memory = []
   let off
@@ -17,19 +18,22 @@ export function createHistory(onChange, options) {
     }
   }
 
-  if (mode !== 'memory') {
-    off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onPop)
-  }
+  function listen(onChange) {
+    onPop = () => onChange(getUrl())
 
-  function onPop() {
-    onChange(getUrl())
-  }
+    if (mode !== 'memory') {
+      off = on(window, mode === 'history' ? 'popstate' : 'hashchange', onPop)
+      raf(onPop)
+    }
 
-  if (mode !== 'memory') {
-    onChange(getUrl())
+    return () => {
+      destroyed = true
+      off && off()
+    }
   }
 
   return {
+    listen,
     getUrl,
     push(url) {
       go(url)
@@ -37,10 +41,6 @@ export function createHistory(onChange, options) {
     replace(url) {
       go(url, true)
     },
-    destroy() {
-      destroyed = true
-      off && off()
-    },
   }
 
   function go(url, replace) {

package/src/router.js

@@ -16,37 +16,41 @@ export function createRouter(options = {}) {
       }
 
       routes = flatten(routeMap)
-      const onHistoryChange = (url) => transition(router, url, cb)
-      history = createHistory(onHistoryChange, { mode, sync })
+      history = createHistory({ mode, sync })
+      const dispose = history.listen((url) => transition(router, url, cb))
 
       return () => {
-        history.destroy()
+        dispose()
         history = null
         routes = []
       }
     },
 
-    navigate(to) {
-      let url
-      let replace = false
-
-      if (to.url) {
-        url = to.url
-      } else {
-        url = router.href(to)
+    navigate(to, curr) {
+      if (typeof to === 'string') {
+        to = { url: to }
       }
-      replace = !!to.replace
-
-      if (replace) {
+      const url = router.href(to, curr)
+      if (to.replace) {
         history.replace(url)
       } else {
         history.push(url)
       }
     },
 
-    href(to) {
+    href(to, curr) {
+      // already a url
+      if (typeof to === 'string') {
+        return to
+      }
+
+      // align with navigate API
+      if (to.url) {
+        return to.url
+      }
+
       if (to.merge) {
-        const curr = to.merge === true ? router.match(router.getUrl()) : to.merge
+        curr = curr || router.match(router.getUrl())
         to = merge(curr, to)
       }
 
@@ -123,7 +127,7 @@ function redirectUrl(router, redirect, matchingRoute) {
   if (typeof redirect === 'function') {
     redirect = redirect(matchingRoute)
   }
-  return redirect.url ? redirect.url : router.href(redirect)
+  return router.href(redirect)
 }
 
 function data(routes, matchingRoute) {
@@ -135,7 +139,7 @@ function data(routes, matchingRoute) {
 }
 
 export function merge(curr = {}, to) {
-  const pathname = to.pathname || curr.pattern
+  const pathname = to.pathname || curr.pattern || curr.pathname
   const params = Object.assign({}, curr.params, to.params)
   const query = to.query === null ? null : Object.assign({}, curr.query, to.query)
   const hash = to.hash === null ? null : to.hash || curr.hash || ''

package/test/router.test.js

@@ -13,13 +13,14 @@ test('createRouter, listen, navigate and dispose', (t) => {
   router.navigate({ url: '/user/7/friends' })
   router.navigate({ url: '/user/7' })
   router.navigate({ url: '/user/8/posts' })
-  router.navigate({ url: '/bar' })
-  router.navigate({ url: '/user/1' })
+  router.navigate('/bar')
+  router.navigate('/user/1')
   router.navigate({ pathname: '/user/:id', params: { id: 2 } })
   router.navigate({ pathname: '/user/2', query: { a: 1, b: 2 } })
   router.navigate({ query: { a: 11, b: 22 }, merge: true })
   router.navigate({ query: { b: undefined, c: 'bla' }, hash: 'test', merge: true })
   router.navigate({ params: { id: 3 }, merge: true })
+  router.navigate({ query: { curr: 'test' }, merge: true }, { pathname: '/user/curr' })
 
   t.deepEqual(
     [
@@ -35,6 +36,7 @@ test('createRouter, listen, navigate and dispose', (t) => {
       'user=2?a=11&b=22',
       'user=2?a=11&c=bla#test',
       'user=3?a=11&c=bla#test',
+      'user=curr?curr=test',
     ],
     calls
   )
@@ -42,7 +44,7 @@ test('createRouter, listen, navigate and dispose', (t) => {
   dispose()
 })
 
-test('.href(options)', (t) => {
+test('.href(to)', (t) => {
   const { router, dispose } = createTestRouter()
 
   t.deepEqual('/user/7/friends?a=1&b=2', router.href({ pathname: '/user/7/friends', query: { a: 1, b: 2 } }))
@@ -107,7 +109,7 @@ test('.match(url) without catch all', (t) => {
 test('.getUrl()', (t) => {
   const { router } = createTestRouter()
 
-  router.navigate({ url: '/user/8' })
+  router.navigate('/user/8')
   t.is(router.getUrl(), '/user/8')
 })
 
@@ -118,10 +120,10 @@ test('redirects', (t) => {
     calls.push(route.data[0].render(route.params, route.query))
   })
 
-  router.navigate({ url: '/redirect-via-obj-1' })
-  router.navigate({ url: '/redirect-via-obj-2' })
-  router.navigate({ url: '/redirect-via-fn-1/2' })
-  router.navigate({ url: '/redirect-via-fn-2/2' })
+  router.navigate('/redirect-via-obj-1')
+  router.navigate('/redirect-via-obj-2')
+  router.navigate('/redirect-via-fn-1/2')
+  router.navigate('/redirect-via-fn-2/2')
 
   t.deepEqual(['bar', 'user=1', 'user=2', 'foo'], calls)
 
@@ -134,7 +136,7 @@ function createTestRouter(cb, { withoutCatchAll = false } = {}) {
     [
       { path: '/foo', render: () => 'foo' },
       { path: '/bar', render: () => 'bar' },
-      { path: '/redirect-via-obj-1', redirect: { url: 'bar' } },
+      { path: '/redirect-via-obj-1', redirect: 'bar' },
       { path: '/redirect-via-obj-2', redirect: { pathname: '/user/:id', params: { id: 1 } } },
       { path: '/redirect-via-fn-1/:id', redirect: ({ params }) => ({ pathname: '/user/:id', params }) },
       { path: '/redirect-via-fn-2/:id', redirect: ({ params }) => ({ url: '/foo' }) },