add navigation.getRoute() and deprecate navigation.steady(), navigati…

…on.getSteadyValue()

packages/navi/src/Navigation.ts

@@ -162,7 +162,7 @@ export class Navigation<Context extends object = any>
     })
     this._history.go(n)
     await urlChanged
-    return this.getSteadyValue()
+    return this.getRoute()
   }
 
   goBack() {
@@ -229,7 +229,7 @@ export class Navigation<Context extends object = any>
 
     this._history[shouldReplace ? 'replace' : 'push'](nextLocation)
 
-    return this.getSteadyValue()
+    return this.getRoute()
   }
 
   // TODO:
@@ -244,38 +244,59 @@ export class Navigation<Context extends object = any>
     })
   }
 
-  refresh() {
+  refresh(): Promise<Route> {
     this.handleURLChange(createURLDescriptor(this._history.location), true)
+    return this.getRoute()
   }
 
-  setContext(context: Context) {
+  setContext(context: Context): Promise<Route> {
     this._router.setContext(context)
-    this.refresh()
+    return this.refresh()
   }
 
   /**
-   * Get the latest route
+   * Get the latest Route object, regardless of whether it is loading.
+   * 
+   * This is named as `getCurrentValue()` so that Navigation objects can be
+   * used with React's `createSubscription()`, and other tools that follow
+   * the same specification.
    */
   getCurrentValue(): Route {
     return this.lastRoute!
   }
 
   /**
-   * Returns a promise that resolves once the route is steady.
-   * This is useful for implementing static rendering, or for waiting until
-   * view is loaded before making the first render.
+   * If loading, returns a promise to the non-busy route. Otherwise, returns
+   * the current route.
    */
-  async getSteadyValue(): Promise<Route> {
+  async getRoute(): Promise<Route> {
     if (this.isLastRouteSteady) {
-      return Promise.resolve(this.lastRoute!)
+      return this.lastRoute!
     } else if (!this.waitUntilSteadyDeferred) {
       this.waitUntilSteadyDeferred = new Deferred()
     }
     return this.waitUntilSteadyDeferred.promise
   }
 
+  /**
+   * Returns a promise that resolves once the route is steady.
+   * This is useful for implementing static rendering, or for waiting until
+   * view is loaded before making the first render.
+   */
+  async getSteadyValue(): Promise<Route> {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('Deprecation Warning: "navigation.getSteadyValue()" will be removed in Navi 0.13. Please use navigation.getRoute() instead.')
+    }
+
+    return this.getRoute()
+  }
+
   async steady() {
-    await this.getSteadyValue()
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn('Deprecation Warning: "navigation.steady()" will be removed in Navi 0.13. Please use navigation.getRoute() instead.')
+    }
+
+    await this.getRoute()
   }
 
   extract(location?): NaviStates {

packages/navi/test/Basename.test.ts

@@ -9,7 +9,7 @@ describe("basename", () => {
       routes: fixtureMap,
     })
 
-    let route = await nav.getSteadyValue()
+    let route = await nav.getRoute()
 
     expect(route.title).toBe('Basic example')
   })
@@ -21,7 +21,7 @@ describe("basename", () => {
       routes: fixtureMap,
     })
 
-    let route = await nav.getSteadyValue()
+    let route = await nav.getRoute()
 
     expect(route.title).toBe('Basic example')
   })

packages/navi/test/BrowserNavigation.test.ts

@@ -56,7 +56,7 @@ describe("BrowserNavigation", () => {
   test("matchers have access to method, body and headers", async () => {
     let nav = createTestNavigation()
     let originalHistoryLength = window.history.length
-    await nav.steady()
+    await nav.getRoute()
     let r = await nav.navigate('/test', {
       body: 'hello',
       headers: { token: 'auth' },
@@ -72,25 +72,21 @@ describe("BrowserNavigation", () => {
     let nav = createTestNavigation()
     let originalHistoryLength = window.history.length
     nav.navigate('/test#1')
-    nav.navigate('/test#2')
-
-    await nav.steady()
+    await nav.navigate('/test#2')
 
     expect(window.history.length).toBe(originalHistoryLength + 2)
   })
 
   test("navigating to exactly the current URL defaults to replace instead of push", async () => {
     let nav = createTestNavigation()
     let originalHistoryLength = window.history.length
-    await nav.steady()
+    await nav.getRoute()
     nav.navigate('/test', {
       body: 'hello',
       headers: { token: 'auth' },
       method: 'POST',
     })
-    nav.navigate('/test')
-
-    let r = await nav.getSteadyValue()
+    let r = await nav.navigate('/test')
 
     expect(r.views[0].method).toBe('GET')
     expect(window.history.length).toBe(originalHistoryLength + 1)
@@ -123,9 +119,8 @@ describe("BrowserNavigation", () => {
       headers: { token: 'auth' },
       method: 'POST',
     })
-    nav.navigate('/')
+    await nav.navigate('/')
 
-    await nav.steady()
     let r = await nav.goBack()
 
     expect(window.history.length).toBe(originalHistoryLength + 2)
@@ -144,9 +139,7 @@ describe("BrowserNavigation", () => {
       headers: { token: 'auth' },
       method: 'POST',
     })
-    nav.navigate('/')
-
-    await nav.steady()
+    await nav.navigate('/')
 
     let r = await nav.goBack()
 
@@ -166,17 +159,15 @@ describe("BrowserNavigation", () => {
         headers: { token: 'auth' },
         method: 'POST',
       })
-      nav.navigate('/')
-
-      await nav.steady()
+      await nav.navigate('/')
       await nav.goBack()
 
       let nav1 = createBrowserNavigation({
         serverStates: nav.extract(),
         routes: createRoutes()
       })
 
-      let r = await nav1.getSteadyValue()
+      let r = await nav1.getRoute()
 
       expect(window.history.length).toBe(originalHistoryLength + 2)
       expect(r.url.pathname).toBe('/test')

packages/navi/test/Integration.test.ts

@@ -12,7 +12,7 @@ describe("integration", () => {
     test("integration", async () => {
         let nav = createTestNavigation('/examples')
 
-        let route = await nav.getSteadyValue()
+        let route = await nav.getRoute()
         let firstChunk = route.chunks[0]
 
         expect(firstChunk.type).toBe('url')
@@ -31,26 +31,23 @@ describe("integration", () => {
         expect(firstChunk.url.query).toEqual({ referrer: 'frontarm' })
         expect(route.type).toEqual('busy')
 
-        route = await nav.getSteadyValue()
+        route = await nav.getRoute()
 
         expect(route.url.query).toEqual({ referrer: 'frontarm' })
         expect(route.title).toBe('Advanced example')
         expect(route.data['isPaywalled']).toBe(true)
         expect(route.views[route.views.length - 1]).toBe('please-login')
 
-        nav.setContext({
+        route = await nav.setContext({
             isAuthenticated: true
         })
 
-        route = await nav.getSteadyValue()
 
         expect((route.lastChunk as ViewChunk).view).toEqual({
             isPaywalled: true,
         })
 
-        nav.navigate('/examples/intermediate')
-
-        route = await nav.getSteadyValue()
+        route = await nav.navigate('/examples/intermediate')
 
         expect(route.error).toBeInstanceOf(NotFoundError)
         expect(route.error && route.error.pathname).toBe("/examples/intermediate")

packages/navi/test/MemoryNavigation.test.ts

@@ -14,7 +14,7 @@ describe("MemoryNavigation", () => {
       }
     })
 
-    let r = await nav.getSteadyValue()
+    let r = await nav.getRoute()
 
     expect(r.views[0]).toBe('result')
   })

packages/navi/test/MountMatcher.test.ts

@@ -10,7 +10,7 @@ describe("Mount", () => {
       }),
     })
 
-    let r = await nav.getSteadyValue()
+    let r = await nav.getRoute()
 
     expect(r.url.pathname).toBe('/to')
     expect(r.url.query.from).toBe('/from')

packages/navi/test/NotFound.test.ts

@@ -11,20 +11,20 @@ describe("pageMap", () => {
 
   test("accessing a undeclared path results in a NotFoundError", async () => {
       let navi = createMemoryNavigation({ routes: routes, url: '/undeclared' })
-      let route = await navi.getSteadyValue()
+      let route = await navi.getRoute()
       expect(route.error).toBeInstanceOf(NotFoundError)
       expect(route.error.pathname).toBe('/undeclared')
   })
 
   test("getView can choose not to throw a NotFoundError", async () => {
     let navi = createMemoryNavigation({ routes: routes, url: '/declared/1' })
-    let route = await navi.getSteadyValue()
+    let route = await navi.getRoute()
     expect(route.error).toBeFalsy()
   })
 
   test("accessing a declared path that throws NotFoundError results in a NotFoundError", async () => {
     let navi = createMemoryNavigation({ routes: routes, url: '/declared/2' })
-    let route = await navi.getSteadyValue()
+    let route = await navi.getRoute()
     expect(route.error).toBeInstanceOf(NotFoundError)
     expect(route.error.pathname).toBe('/declared/2')
   })

packages/navi/test/RedirectMatcher.test.ts

@@ -12,7 +12,7 @@ describe("Redirect", () => {
       }),
     })
 
-    let r = await nav.getSteadyValue()
+    let r = await nav.getRoute()
 
     expect(r.url.pathname).toBe('/switch/to')
   })

packages/navi/test/ViewMatcher.test.ts

@@ -10,7 +10,7 @@ describe("ViewMatcher", () => {
       trailingSlash: null,
     })
 
-    let r = await nav.getSteadyValue()
+    let r = await nav.getRoute()
 
     expect(r.url.pathname).toBe('/test/')
   })
@@ -23,7 +23,7 @@ describe("ViewMatcher", () => {
       }),
     })
 
-    let r = await nav.getSteadyValue()
+    let r = await nav.getRoute()
 
     expect(r.data.title).toBe('/test')
   })
@@ -37,7 +37,7 @@ describe("ViewMatcher", () => {
       trailingSlash: null,
     })
 
-    let r = await nav.getSteadyValue()
+    let r = await nav.getRoute()
 
     expect(r.url.pathname).toBe('/test')
   })