update docs to match latest changes

Author: josepot

docs/api/core/bind.md

@@ -8,20 +8,23 @@ Binds an Observable to React, and returns a hook and shared stream representing
 ```ts
 function bind<T>(
   observable: Observable<T>,
+  defaultValue?: T,
 ): [() => Exclude<T, typeof SUSPENSE>, Observable<T>]
 ```
 
 #### Arguments
 
 - `observable`: The source Observable to be used by the hook.
+- `defaultValue`: (Optional) value to return when the source hasn't emitted yet.
 
 #### Returns
 
 `[1, 2]`:
 
 1. A React Hook that yields the latest emitted value of the Observable. If the
-   Observable doesn't synchronously emit a value upon the first subscription, then
-   the hook will leverage React Suspense while it's waiting for the first value.
+   Observable doesn't synchronously emit a value, it will return the
+   `defaultValue` if provided, otherwise it will leverage React Suspense
+   while it's waiting for the first value.
 
 2. The shared Observable that the hook uses: It also replays back the latest
    value emitted. It can be used for composing other streams that depend on it.
@@ -58,6 +61,7 @@ Binds an Observable factory function to React, and returns a hook and shared str
 ```ts
 function bind<A extends unknown[], O>(
   getObservable: (...args: A) => Observable<O>,
+  defaultValue?: T,
 ): [(...args: A) => Exclude<O, typeof SUSPENSE>, (...args: A) => Observable<O>]
 ```
 
@@ -66,18 +70,15 @@ function bind<A extends unknown[], O>(
 - `getObservable`: Factory of Observables. The arguments of this function
   will be the ones used in the hook.
 
-:::note
-It's important that the observable returned by `getObservable` shouldn't make the side-effect (or request) on subscription - Instead, it should take the needed value from other existing streams. See [Core Concepts - instances](core-concepts.md#instances) for more info
-:::
-
 #### Returns
 
 `[1, 2]`:
 
 1. A React hook with the same arguments as the factory function. This hook
    will yield the latest update from the Observable returned from the factory function.
-   If the Observable doesn't synchronously emit a value upon the first subscription, then
-   the hook will leverage React Suspense while it's waiting for the first value.
+   If the Observable doesn't synchronously emit a value, it will return the
+   `defaultValue` if provided, otherwise it will leverage React Suspense
+   while it's waiting for the first value.
 
 2. The factory function that returns the shared Observable that the hook uses
    for the specific arguments. It can be used for composing other streams that depend on it.

docs/api/core/subscribe.md

@@ -6,22 +6,26 @@ title: <Subscribe />
 A React Component that creates a subscription to the provided Observable once
 the component mounts, and unsubscribes when the component unmounts.
 
+It also acts as a Suspense boundary, rendering a fallback element until the
+suspended element resolves.
+
 ```tsx
 const Subscribe: React.FC<{
-    source$: Observable<any>;
-    fallback?: JSX.Element;
+  source$: Observable<any>
+  fallback?: JSX.Element
 }>
 ```
 
 #### Properties
 
 - `source$`: Source Observable that the Component will subscribe to.
-- `fallback`: (Optional) The JSX Element to be rendered 
-before the subscription is created. Default: `null`.
+- `fallback`: (Optional) The JSX Element to be rendered before the
+  subscription is created. Default: `null`.
 
 :::note Important
 This Component doesn't trigger any updates.
 :::
 
 ## See also
-* [`useSubscribe()`](useSubscribe)
+
+- [`useSubscribe()`](useSubscribe)

docs/core-concepts.md

@@ -4,7 +4,7 @@ title: Core Concepts
 
 ## Push vs Pull
 
-Historically, React uses a **pull**-based architecture. This means that when React needs to re-render, it will call the render function of every affected component. This will return a new representation of the UI, which React can reconcile with the previous one. Any changes are then propogated to the DOM.
+Historically, React uses a **pull**-based architecture. This means that when React needs to re-render, it will call the render function of every affected component. This will return a new representation of the UI, which React can reconcile with the previous one. Any changes are then propagated to the DOM.
 
 This kind of behavior is called _pull_ because the consumer (in this case, React), is the one that _requests_ the new value.
 
@@ -121,17 +121,17 @@ const [useFirst5SpacedNumbers, first5SpacedNumbers$] = bind(
 
 `useFirst5SpacedNumbers` is a hook that will return just a number, which is shared for all components that use it.
 
-Something important to note, though, is that the subscription will happen as soon as there's a subscriber and it will be alive until there are no more subscribers. This means that if all of the components that subscribe to this stream unmount for a while, the latest value will be forgotten, and it will restart the stream when there's a new subscription.
+Something important to note, though, is that the subscription to the shared observable (in this case, `first5SpacedNumbers$`) must have an active subscription before the hook can execute. We can't rely on React renderer to make the initial subscription for us (the subscription which would trigger the side effect), because we can't rely on when rendering happens, nor if it will be interrupted or cancelled.
 
-For this reason, it's important to understand that these streams only represent state. React can subscribe to any of these at any time to read the state. If the subscription is alive at that moment, then it will receive the latest value, but if it isn't, a new subscription will be made (possibly making a request to the server).
+This means that we need manage the subscription logic for the stream, in order to have full control over when to execute the initial subscription.
 
-If you want to keep one of these streams alive for as long as you need, React-RxJS also exposes `useSubscribe(stream)` and `<Subscribe source$={stream}>{ content }</Subscribe>`, which will render `{ content }` only after it subscribed to `stream`.
+There are many ways of doing that, but React-RxJS provides a utility to make it easier: `<Subscribe source$={stream}>{ content }</Subscribe>` will render `{ content }` only after subscribing to its `$source`. It also acts as a Suspense boundary, so you can also provide a `fallback` element.
 
 With the mental model of "streams as state", it's also worth noting that the observables returned by `bind` won't complete: If the source of that observable completes, it will keep the last value and replay it back to new subscribers, as a completion on the source means that there won't be more changes to that stream. Remember that if the subscriber count reaches 0, this state will be cleaned up, and the subscription will restart when a new observer subscribes later on.
 
 ## Composing streams
 
-You might have noticed that `bind` returns the hook inside a tuple. This is because `bind` also exposes the stream with `shareLatest` applied so it can be easily composed.
+As the stream returned by `bind` is shared, it can be easily composed with other streams.
 
 ```ts
 import { interval } from "rxjs"
@@ -186,14 +186,12 @@ And now the "TodoForm" component can directly call `postNewTodo` whenever the us
 
 Keep in mind that `bind` doesn't do magic. If no one is subscribed to `todoList$` (not even from the hook) then that stream won't be listening for changes on `newTodos` subject, and if a subscription happens late, the subject won't replay the todos created, so they would get lost.
 
-Remember, if you have a case like this (where you are pushing a Subject but no one is subscribed to those changes), make sure you have an active subscription to the stream by using `<Subscribe source$={stream} />` or `useSubscribe(stream)`. This way, `todoList$` will update when a new value is pushed to the subject, and the result will be replayed for every new subscriber that arrives later.
+This can be easily prevent if the component that would call `postNewTodo` is also inside the boundary `<Subscribe source$={todoList$}>` - Which in this case it would make sense as it's probably part of the same feature.
 
 ## Instances
 
 There are many times where you need components to access a particular instance - Classic example is a list of posts. To help with that, `bind` can also take a factory function that returns an Observable for that instance.
 
-However, when using this overload it's important that this observable shouldn't make the actual request, because it's hard to manage the lifecycle of these observables (when they subscribe, and when they can clean up) - Instead, it should take the value from an existing Observable-state.
-
 For example, if we have a list of posts, we might have an observable that has all of them in a dictionary:
 
 ```ts
@@ -221,54 +219,25 @@ import { bind } from "@react-rxjs/core"
 const [useTodos, todo$] = bind(ajax.getJSON("/todos"))
 ```
 
-You might be wondering - how does this _exactly_ work with React? If React is pull-based and it _needs_ a value at the time it's re-rendering, this stream won't have a value until the ajax call is resolved.
+You might be wondering - how does this _exactly_ work with React? If React is pull-based and it _needs_ a value at the time it's re-rendering, this stream might not have a value until the ajax call is resolved.
 
 Well, React added a feature called Suspense. With Suspense, we can represent values that are not yet ready, and we can notify React when those values have been loaded.
 
 `react-rxjs` comes with full support for Suspense, and it treats it as a first-class citizen. This means that by default, using a hook from a stream that hasn't emitted any value will result in that hook suspending the component.
 
-Note that for this to work properly, you need to have proper Suspense boundaries throughout your component tree. If you don't want to use Suspense just yet, the solution is simple: Make sure that the stream always has a value. In our example, if we decide that `null` represents missing values, the solution is as simple as:
+Note that for this to work properly, you need to have proper Suspense boundaries throughout your component tree. If you don't want to use Suspense just yet, the solution is simple: Make sure that the stream always has a value. This can be done through RxJS' `startWith`, but `bind` can also take an optional parameter for the default value:
 
 ```ts
 import { ajax } from "rxjs/ajax"
-import { startWith } from "rxjs/operators"
 import { bind } from "@react-rxjs/core"
 
-const [useTodos, todos$] = bind(ajax.getJSON("/todos").pipe(startWith(null)))
+const [useTodos, todos$] = bind(ajax.getJSON("/todos"), null)
 ```
 
 Now `useTodos` will emit `null` immediately while it's fetching data (so that we can manually handle that), instead of suspending the component, and when the ajax call is resolved, it will emit the result of that call.
 
 When using Suspense, however, there's also another way to suspend a component with `react-rxjs`: by emitting `SUSPENSE`. For example, this can come in handy if you need to refresh the data because some filter has changed.
 
-There's something to keep in mind though: React Suspense works in a serialized way within a Component. Imagine this example:
-
-```tsx
-const UserProfile = () => {
-  const details = useUserDetails()
-  const posts = useUserPosts()
-
-  return (
-    <div>
-      <UserDetails details={details} />
-      <UserPosts posts={posts} />
-    </div>
-  )
-}
-```
-
-In this case, because of the way that Suspense works, these fetches will happen in sequential order. This means that initially `useUserDetails` will subscribe to `userDetails$`, which will start fetching data and suspend the component. When the fetch call resolves, `useUserDetails` will "resume" the component, and `useUserPosts` will run, subscribing and fetching the data, and suspending the component yet again.
-
-This is usually a code smell. If you need to use many react-rxjs hooks in a component, each of which will do some asynchronous work, it's often better to move this logic into a single stream (and hook) by using composition:
-
-```ts
-const [useUserDetailsAndPosts] = bind(combineLatest(userDetail$, userPosts$))
-```
-
-Now `useUserDetailsAndPosts` will start fetching both resources and suspend the component just once for both of them.
-
-However, in this particular example, there is an even better solution. Note that `UserProfile` is not using `details` or `posts` directly, so we can move the usage of those two hooks down into the components that actually use them, `<UserDetails />` and `<UserPosts />`. This way, React will render both components, and both of them will suspend at the same time, while also subscribing to both streams simultaneously.
-
 ## Error boundaries
 
 React 16 added the concept of Error Boundaries: A way to catch errors in the component tree and show a fallback UI so it can be recovered from.
@@ -285,7 +254,7 @@ import { interval } from "rxjs"
 import { map, startWith } from "rxjs/operators"
 import { ErrorBoundary } from "react-error-boundary"
 
-const [useTimedBomb] = bind(
+const [useTimedBomb, timedBomb$] = bind(
   interval(1000).pipe(
     map((v) => v + 1),
     startWith(0),
@@ -319,7 +288,9 @@ function App() {
   return (
     <div className="App">
       <ErrorBoundary FallbackComponent={ErrorFallback}>
-        <Bomb />
+        <Subscribe source$={timedBomb$}>
+          <Bomb />
+        </Subscribe>
       </ErrorBoundary>
     </div>
   )
@@ -328,6 +299,6 @@ function App() {
 
 In here, `useTimedBomb` will start counting from 0 and emit an `error` in the 3rd second. React-RxJS ensures that this error will be caught in the ErrorBoundary defined for the component that's using this stream, so the fallback UI will be shown.
 
-When a rxjs stream emits an error, the stream gets immediately closed. This way, if our strategy to recover from the error is to try again, when `Bomb` resubscribes to the stream it will create a new subscription and start over again.
+When a rxjs stream emits an error, the stream gets immediately closed. This way, if our strategy to recover from the error is to try again, when our `Subscribe` boundary resubscribes to the stream it will create a new subscription and start over again.
 
 In this case, after 3 seconds it will throw an error again, but in a real-world case this might be different, and you might need different recovery strategies depending on each case. `react-error-boundary` helps by providing a declarative way to define these strategies.

docs/examples/CharacterCounter.jsx

@@ -1,7 +1,7 @@
 import React from "react"
 import { Subject } from "rxjs"
 import { map, startWith } from "rxjs/operators"
-import { bind } from "@react-rxjs/core"
+import { bind, Subscribe } from "@react-rxjs/core"
 
 const textSubject = new Subject()
 const setText = (newText) => textSubject.next(newText)
@@ -23,7 +23,7 @@ function TextInput() {
   )
 }
 
-const [useCharCount] = bind(text$.pipe(map((text) => text.length)))
+const [useCharCount, charCount$] = bind(text$.pipe(map((text) => text.length)))
 
 function CharacterCount() {
   const count = useCharCount()
@@ -34,8 +34,10 @@ function CharacterCount() {
 export default function CharacterCounter() {
   return (
     <div>
-      <TextInput />
-      <CharacterCount />
+      <Subscribe source$={charCount$}>
+        <TextInput />
+        <CharacterCount />
+      </Subscribe>
     </div>
   )
 }

docs/getting-started.md

@@ -3,6 +3,7 @@ title: Getting Started
 ---
 
 import CharacterCounter from "./examples/CharacterCounter"
+import BrowserOnly from '@docusaurus/BrowserOnly';
 
 ## Installation
 
@@ -52,12 +53,12 @@ function TextInput() {
 
 ```tsx
 import { map } from "rxjs/operators"
-import { bind } from "@react-rxjs/core"
+import { bind, Subscribe } from "@react-rxjs/core"
 
 // Previously...
 // const [useText, text$] = bind(...);
 
-const [useCharCount] = bind(text$.pipe(map((text) => text.length)))
+const [useCharCount, charCount$] = bind(text$.pipe(map((text) => text.length)))
 
 function CharacterCount() {
   const count = useCharCount()
@@ -66,22 +67,26 @@ function CharacterCount() {
 }
 ```
 
-If we put everything together
+Something to note is that a subscription on the underlying observable must be present before the hook is executed. We can use `Subscribe` to help us with it:
 
 ```tsx
 function CharacterCounter() {
   return (
     <div>
-      <TextInput />
-      <CharacterCount />
+      <Subscribe source$={charCount$}>
+        <TextInput />
+        <CharacterCount />
+      </Subscribe>
     </div>
   )
 }
 ```
 
 This is shown as:
 
-<CharacterCounter />
+<BrowserOnly>
+  {() => <CharacterCounter />}
+</BrowserOnly>
 
 ## Next steps
 

package.json

@@ -11,7 +11,7 @@
   "dependencies": {
     "@docusaurus/core": "^2.0.0-alpha.63",
     "@docusaurus/preset-classic": "^2.0.0-alpha.63",
-    "@react-rxjs/core": "^0.1.2",
+    "@react-rxjs/core": "^0.6.1",
     "clsx": "^1.1.1",
     "react": "^16.8.4",
     "react-dom": "^16.8.4",

yarn.lock

@@ -1588,10 +1588,10 @@
   dependencies:
     mkdirp "^1.0.4"
 
-"@react-rxjs/core@^0.1.2":
-  version "0.1.2"
-  resolved "https://registry.yarnpkg.com/@react-rxjs/core/-/core-0.1.2.tgz#5c2fab5500efd7ac359c00845fbdd9b7f0b70ead"
-  integrity sha512-Lztpv681KC8eT5hRj+ndVw8mPRxREAx2ZI5QBSBNfvVammERV64ZqBGaeg6mnYJp5Hr0Dv4G6QME2M+kq3J5PA==
+"@react-rxjs/core@^0.6.1":
+  version "0.6.1"
+  resolved "https://registry.yarnpkg.com/@react-rxjs/core/-/core-0.6.1.tgz#d2d401bdcb72baf7b5ecdf59d4b809bd044d2f0e"
+  integrity sha512-E2LXU+udZpaoy528IKVaIzuwcB7IEcBL9caWdnPx25B7SaoBo5BTVnuLNdTVZjjwExCBBeg0NO3Nmj408lMLvw==
 
 "@sindresorhus/is@^0.14.0":
   version "0.14.0"