Voidable sub factory, reactive ready, and a Readme

Author: CaptainN

packages/react-mongo/README.md

@@ -1,4 +1,44 @@
 meteor/react-mongo
 ==================
 
+```
+meteor add meteor/react-mongo
+```
+
 A set of hooks for using Meteor's Mini Mongo Collections and pub/sub.
+
+There are two hooks
+
+| Hook | Function
+| ---- | --------
+| useSubscription | Used to set up a Meteor subscription. In SSR, this hook is responsible for capturing data to be sent to the client for hydration.
+| useCursor | Manages the lifecycle of a Mongo Cursor
+
+Both methods accept a factory method, and deps.
+
+## useSubscription(factory, deps)
+
+`useSubscription` takes a factory method, which should return a subscription handle, and a deps array. It can also return `void` to conditionally set up no subscription. The hook returns a subscription handle with a reactive `ready` method.
+
+Invoking the `ready()` handle method will cause the hook to update react when the subscription becomes available.
+
+### Example
+
+```jsx
+import React from 'react'
+import { useSubscription } from 'meteor/react-mongo'
+
+const MyComponent = ({ id = null }) => {
+  const subscription = useSubscription(() => {
+    if (id) return Meteor.subscribe(id)
+  }, [id])
+
+  return <div>
+    {
+      subscription.ready()
+        ? 'content ready'
+        : 'loading...'
+    }
+  </div>
+}
+```

packages/react-mongo/react-mongo.ts

@@ -6,33 +6,54 @@ import { useEffect, useMemo, useReducer, useRef, DependencyList } from 'react'
 const fur = (x: number): number => x + 1
 const useForceUpdate = () => useReducer(fur, 0)[1]
 
-const useSubscriptionClient = (factory: () => Meteor.SubscriptionHandle, deps: DependencyList = []) => {
+const useSubscriptionClient = (factory: () => Meteor.SubscriptionHandle | void, deps: DependencyList= []) => {
   const forceUpdate = useForceUpdate()
-  const subscription = useRef<Meteor.SubscriptionHandle>({
-    stop() {},
-    ready: () => false
+  const { current: refs } = useRef<{
+    handle?: Meteor.SubscriptionHandle,
+    updateOnReady: boolean
+  }>({
+    handle: {
+      stop () {
+        refs.handle?.stop()
+      },
+      ready () {
+        refs.updateOnReady = true
+        return refs.handle?.ready()
+      }
+    },
+    updateOnReady: false
   })
 
   useEffect(() => {
-    const computation = Tracker.autorun(() => {
-      subscription.current = factory()
-      if (subscription.current.ready()) forceUpdate()
-    })
+    // Use Tracker.nonreactive in case we are inside a Tracker Computation.
+    // This can happen if someone calls `ReactDOM.render` inside a Computation.
+    // In that case, we want to opt out of the normal behavior of nested
+    // Computations, where if the outer one is invalidated or stopped,
+    // it stops the inner one.
+    const computation = Tracker.nonreactive(() => (
+      Tracker.autorun(() => {
+        refs.handle = factory()
+        if (!refs.handle) return
+        if (refs.updateOnReady && refs.handle.ready()) {
+          forceUpdate()
+        }
+      })
+    ))
 
     return () => {
       computation.stop()
     }
   }, deps)
 
-  return subscription.current
+  return refs.handle
 }
 
 const useSubscriptionServer = (): Meteor.SubscriptionHandle => ({
   stop() {},
   ready() { return true }
 })
 
-export const useSubscription = (factory: () => Meteor.SubscriptionHandle, deps: DependencyList = []) => (
+export const useSubscription = (factory: () => Meteor.SubscriptionHandle | void, deps: DependencyList = []) => (
   Meteor.isServer
     ? useSubscriptionServer()
     : useSubscriptionClient(factory, deps)

packages/react-mongo/types/react-mongo.d.ts

@@ -1,5 +1,10 @@
 import { Meteor } from 'meteor/meteor';
 import { Mongo } from 'meteor/mongo';
 import { DependencyList } from 'react';
-export declare const useSubscription: (factory: () => Meteor.SubscriptionHandle, deps?: DependencyList) => Meteor.SubscriptionHandle;
+declare type UseSubscriptionOptions = {
+    deps?: DependencyList;
+    updateOnReady?: boolean;
+};
+export declare const useSubscription: (factory: () => Meteor.SubscriptionHandle | void, deps?: DependencyList | UseSubscriptionOptions) => void;
 export declare const useCursor: <T = any>(factory: () => Mongo.Cursor<T>, deps?: DependencyList) => Mongo.Cursor<T>;
+export {};