From 0460b9164f08964da1fcf055a92bf009bb5296c4 Mon Sep 17 00:00:00 2001 From: Josep M Sobrepere Date: Mon, 29 Jun 2020 02:56:49 +0200 Subject: [PATCH] docs: Improve README and JSDocs --- README.md | 42 ++++++++++++++++++++------------- src/connectFactoryObservable.ts | 11 ++++++--- src/connectObservable.ts | 19 +++++++++------ 3 files changed, 46 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index cea5aeb..563148d 100644 --- a/README.md +++ b/README.md @@ -37,14 +37,17 @@ Main features - [Installation](#installation) - [API](#api) - - [connectObservable](#connectObservable) - - [connectFactoryObservable](#connectFactoryObservable) - - [shareLatest](#shareLatest) - - [SUSPENSE](#SUSPENSE) - - [suspend](#suspend) - - [suspended](#suspended) - - [switchMapSuspended](#switchMapSuspended) - - [createInput](#createInput) + - Core + - [connectObservable](#connectObservable) + - [connectFactoryObservable](#connectFactoryObservable) + - [shareLatest](#shareLatest) + - React Suspense Support + - [SUSPENSE](#SUSPENSE) + - [suspend](#suspend) + - [suspended](#suspended) + - [switchMapSuspended](#switchMapSuspended) + - Utils + - [createInput](#createInput) - [Examples](#examples) @@ -62,12 +65,17 @@ const [useCounter, sharedCounter$] = connectObservable( ) ) ``` -Returns a hook that provides the latest update of the accepted observable, and the -underlying enhanced observable, which shares the subscription to all of its subscribers, -and always emits the latest value when subscribing to it. +Accepts: An Observable. -The shared subscription is closed as soon as there are no subscribers to that -observable. +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. + +2. A `sharedLatest` version of the observable that does not complete. It can be +used for composing other streams that depend on it. The shared subscription is +closed as soon as there are no subscribers to that observable. ### connectFactoryObservable ```tsx @@ -86,16 +94,18 @@ const Story: React.FC<{id: number}> = ({id}) => { ) } ``` -Accepts: -A factory function that returns an Observable. +Accepts: A factory function that returns an Observable. Returns `[1, 2]` 1. A React Hook function with the same parameters 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. 2. A `sharedLatest` version of the observable returned by the factory function that does not complete. It can be used for composing other streams that depend on it. +The shared subscription is closed as soon as there are no subscribers to that observable. ### shareLatest ```ts @@ -133,7 +143,7 @@ const story$ = selectedStoryId$.pipe( ``` This is a special symbol that can be emitted from our observables to let the react hook -know that there is a value on its way, and that we want to leverage React Suspense API +know that there is a value on its way, and that we want to leverage React Suspense while we are waiting for that value. ### suspend diff --git a/src/connectFactoryObservable.ts b/src/connectFactoryObservable.ts index 8e47717..73e1f36 100644 --- a/src/connectFactoryObservable.ts +++ b/src/connectFactoryObservable.ts @@ -14,13 +14,18 @@ import { SUSPENSE } from "./SUSPENSE" * the factory function. * 2. A shared replayable version of the observable generated by the factory * function that can be used for composing other streams that depend on it. - * This observable is disposed when its refCount goes down to zero. + * The shared subscription is closed as soon as there are no subscribers to + * that observable. * * @param getObservable Factory of observables. The arguments of this function * will be the ones used in the hook. * @param unsubscribeGraceTime (= 200): Amount of time in ms that the shared - * observable should wait before unsubscribing from the source observable - * when there are no new subscribers. + * observable should wait before unsubscribing from the source observable when + * there are no new subscribers. + * + * @remarks 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. */ export function connectFactoryObservable< A extends (number | string | boolean | null)[], diff --git a/src/connectObservable.ts b/src/connectObservable.ts index d5617fb..1a3ed2e 100644 --- a/src/connectObservable.ts +++ b/src/connectObservable.ts @@ -4,17 +4,22 @@ import reactEnhancer from "./internal/react-enhancer" import { useObservable } from "./internal/useObservable" /** - * Returns a hook that provides the latest update of the accepted observable, - * and the underlying enhanced observable, which shares the subscription to all - * of its subscribers, and always emits the latest value when subscribing to it. + * Accepts: An Observable. * - * The shared subscription is closed as soon as there are no subscribers to that - * observable. + * Returns [1, 2] + * 1. A React Hook that yields the latest emitted value of the observable + * 2. A `sharedLatest` version of the observable that does not complete. It can + * be used for composing other streams that depend on it. The shared subscription + * is closed as soon as there are no subscribers to that observable. * * @param observable Source observable to be used by the hook. * @param unsubscribeGraceTime (= 200): Amount of time in ms that the shared - * observable should wait before unsubscribing from the source observable - * when there are no new subscribers. + * observable should wait before unsubscribing from the source observable when + * there are no new subscribers. + * + * @remarks 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. */ export function connectObservable( observable: Observable,