docs: Adding API docs

packages/rx-effects-react/src/useConst.ts

@@ -2,6 +2,13 @@
 
 import { useRef } from 'react';
 
+/**
+ * Keeps the value as a constant between renders of a component.
+ *
+ * If the factory is provided, it is called only once.
+ *
+ * @param initialValue a value or a factory for the value
+ */
 export function useConst<T>(initialValue: (() => T) | T): T {
   const constRef = useRef<{ value: T } | void>();
 

packages/rx-effects-react/src/useController.ts

@@ -4,6 +4,16 @@
 import { useEffect, useMemo } from 'react';
 import { Controller } from 'rx-effects';
 
+/**
+ * Creates a controller by the factory and destroys it on unmounting a
+ * component
+ *
+ * The factory is not part of the dependencies by default. It should be
+ * included explicitly when it is needed.
+ *
+ * @param factory a controller factory
+ * @param dependencies array of hook dependencies to recreate the controller.
+ */
 export function useController<T extends Controller<Record<string, any>>>(
   factory: () => T,
   dependencies?: unknown[],

packages/rx-effects-react/src/useObservable.ts

@@ -1,6 +1,21 @@
 import { identity, Observable } from 'rxjs';
 import { useSelector } from './useSelector';
 
+/**
+ * Returns a value provided by `source$`.
+ *
+ * The hook returns the initial value and subscribes on the `source$`. After
+ * that, the hook returns values which are provided by the source.
+ *
+ * @param source$ an observable for values
+ * @param initialValue th first value which is returned by the hook
+ * @param comparator a comparator for previous and next values
+ *
+ * @example
+ * ```ts
+ * const value = useObservable<string>(source$, undefined);
+ * ```
+ */
 export function useObservable<T>(
   source$: Observable<T>,
   initialValue: T,

packages/rx-effects-react/src/useObserver.ts

@@ -2,6 +2,22 @@ import { useEffect } from 'react';
 import { Observable, Observer, Subscription } from 'rxjs';
 import { useConst } from './useConst';
 
+/**
+ * Subscribes the provided observer or `next` handler on the source.
+ *
+ * This hook allows to do fine handling of the source observable.
+ *
+ * @param source$ an observable
+ * @param observerOrNext `Observer` or `next` handler
+ *
+ * @example
+ * ```ts
+ * const observer = useCallback((nextValue) => {
+ *   logger.log(nextValue);
+ * }, []);
+ * useObserver(source$, observer);
+ * ```
+ */
 export function useObserver<T>(
   source$: Observable<T>,
   observerOrNext: Partial<Observer<T>> | ((value: T) => void),

packages/rx-effects-react/src/useSelector.ts

@@ -1,22 +1,46 @@
 import { useEffect, useState } from 'react';
 import { Observable } from 'rxjs';
 
+/**
+ * Returns a value provided by `source$`.
+ *
+ * The hook returns the initial value and subscribes on the `source$`. After
+ * that, the hook returns values which are provided by the source.
+ *
+ * @param source$ an observable for values
+ * @param initialValue th first value which is returned by the hook
+ * @param selector a transform function for getting a derived value based on
+ *   the source value
+ * @param comparator a comparator for previous and next values
+ *
+ * @example
+ * ```ts
+ * const value = useSelector<{data: Record<string, string>}>(
+ *   source$,
+ *   undefined,
+ *   (state) => state.data,
+ *   (data1, data2) => data1.key === data2.key
+ * );
+ * ```
+ */
 export function useSelector<S, R>(
-  state$: Observable<S>,
-  initialState: S,
+  source$: Observable<S>,
+  initialValue: S,
   selector: (state: S) => R,
-  compare: (v1: R, v2: R) => boolean = Object.is,
+  comparator: (v1: R, v2: R) => boolean = Object.is,
 ): R {
-  const [value, setValue] = useState<R>(() => selector(initialState));
+  const [value, setValue] = useState<R>(() => selector(initialValue));
 
   useEffect(() => {
-    const subscription = state$.subscribe((state) => {
+    const subscription = source$.subscribe((state) => {
       const value = selector(state);
-      setValue((prevValue) => (compare(value, prevValue) ? prevValue : value));
+      setValue((prevValue) =>
+        comparator(value, prevValue) ? prevValue : value,
+      );
     });
 
     return () => subscription.unsubscribe();
-  }, [compare, selector, state$]);
+  }, [comparator, selector, source$]);
 
   return value;
 }

packages/rx-effects-react/src/useStateQuery.ts

@@ -1,8 +1,13 @@
 import { useEffect, useState } from 'react';
 import { StateQuery } from 'rx-effects';
 
+/**
+ * Provides the current and future values which are provided by the query.
+ *
+ * @param query – a query for a value
+ */
 export function useStateQuery<T>(query: StateQuery<T>): T {
-  const [value, setValue] = useState<T>(() => query.get());
+  const [value, setValue] = useState<T>(query.get);
 
   useEffect(() => {
     const subscription = query.value$.subscribe((nextValue) => {

packages/rx-effects/src/stateMutation.ts

@@ -12,6 +12,9 @@
  * const addPizzaToCart = (name: string): StateMutation<Array<string>> =>
  *   (state) => ([...state, name]);
  * ```
+ *
+ * @param state a previous state
+ * @returns a next state
  */
 export type StateMutation<State> = (state: State) => State;
 

packages/rx-effects/src/store.ts

@@ -50,12 +50,12 @@ export type Store<State> = StateReader<State> &
  * Creates the state store.
  *
  * @param initialState an initial state
- * @param stateCompare a comparator for detecting changes between old and new
+ * @param stateComparator a comparator for detecting changes between old and new
  *   states
  */
 export function createStore<State>(
   initialState: State,
-  stateCompare: (prevState: State, nextState: State) => boolean = Object.is,
+  stateComparator: (prevState: State, nextState: State) => boolean = Object.is,
 ): Store<State> {
   const store$: BehaviorSubject<State> = new BehaviorSubject(initialState);
   const state$ = store$.asObservable();
@@ -69,15 +69,15 @@ export function createStore<State>(
 
     set(nextState: State) {
       const prevState = store$.value;
-      if (!stateCompare(prevState, nextState)) {
+      if (!stateComparator(prevState, nextState)) {
         store$.next(nextState);
       }
     },
 
     update(mutation: StateMutation<State>) {
       const prevState = store$.value;
       const nextState = mutation(prevState);
-      if (!stateCompare(prevState, nextState)) {
+      if (!stateComparator(prevState, nextState)) {
         store$.next(nextState);
       }
     },