From 2087dd4a218b6bc46a83e4ed3f8543bf45ccbc4f Mon Sep 17 00:00:00 2001 From: Dor Shtaif Date: Thu, 19 Dec 2024 14:33:52 +0200 Subject: [PATCH] edits for `useAsyncIter`'s JSDocs --- src/useAsyncIter/index.ts | 70 +++++++++++++++++++++------------------ 1 file changed, 37 insertions(+), 33 deletions(-) diff --git a/src/useAsyncIter/index.ts b/src/useAsyncIter/index.ts index f15f9f0..d3928fa 100644 --- a/src/useAsyncIter/index.ts +++ b/src/useAsyncIter/index.ts @@ -11,15 +11,32 @@ export { useAsyncIter, type IterationResult }; /** * `useAsyncIter` hooks up a single async iterable value into your component and its lifecycle. * + * _Illustration:_ + * + * ```tsx + * import { useAsyncIter } from 'react-async-iterators'; + * + * function SelfUpdatingTodoList(props) { + * const { value: todos } = useAsyncIter(props.todosAsyncIter); + * return ( + * + * ); + * } + * ``` + * * Given an async iterable `input`, this hook will iterate it and rerender the host component upon - * each new value that becomes available as well as any possible completion or error it may run into. + * each new value that becomes available together with any possible completion or error it may run into. * If `input` is a plain (non async iterable) value, it will simply be used to render once and * immediately. * - * The hook inits and maintains its current iteration process across renderings as long as its + * The hook inits and maintains its current iteration process across re-renders as long as its * `input` is passed the same object reference each time (similar to the behavior of a * `useEffect(() => {...}, [input])`), therefore care should be taken to avoid constantly recreating - * the iterable every render, e.g; declaring it outside the component body or control __when__ it + * the iterable every render, e.g; by declaring it outside the component body or control __when__ it * should be recreated with React's [`useMemo`](https://react.dev/reference/react/useMemo). * Whenever `useAsyncIter` detects a different `input` value, it automatically closes a previous * `input` async iterable before proceeding to iterate any new `input` async iterable. The hook will @@ -27,36 +44,21 @@ export { useAsyncIter, type IterationResult }; * * The object returned from `useAsyncIter` holds all the state from the most recent iteration * of `input` (most recent value, whether is completed or still running, etc. - see - * {@link IterationResult}). + * {@link IterationResult `IterationResult`}). * In case `input` is given a plain value, it will be delivered as-is within the returned * result object's `value` property. * + * @template TValue The type of values yielded by the passed iterable or otherwise type of the passed plain value itself. + * @template TInitValue The type of the initial value, defaults to `undefined`. + * * @param input Any async iterable or plain value - * @param initialValue Any initial value for the hook to return prior to resolving the ___first + * @param initialValue Any initial value for the hook to return prior to resolving the ___first * emission___ of the ___first given___ async iterable, defaults to `undefined`. * * @returns An object with properties reflecting the current state of the iterated async iterable - * or plain value provided via `input` (see {@link IterationResult}) + * or plain value provided via `input` (see {@link IterationResult `IterationResult`}) * - * @see {@link IterationResult} - * - * @example - * ```tsx - * // In its simplest: - * - * import { useAsyncIter } from 'react-async-iterators'; - * - * function SelfUpdatingTodoList(props) { - * const { value: todos } = useAsyncIter(props.todosAsyncIter); - * return ( - * - * ); - * } - * ``` + * @see {@link IterationResult `IterationResult`} * * @example * ```tsx @@ -204,10 +206,10 @@ type IterationResult = { value: ExtractAsyncIterValue | TInitVal; /** - * Indicates whether the iterated async iterable is still pending on its own first - * value to be resolved. + * Indicates whether the iterated async iterable is still pending its own first value to be + * resolved. * Will appear `false` for any iterations thereafter and reset back every time the iteratee - * is replaced with a new one. + * is changed to a new one. * * Can be used in certain cases for displaying _"loading" states_ metaphorically similar to * a how a pending state of a promise is thought of. @@ -217,13 +219,15 @@ type IterationResult = { pendingFirst: boolean; /** - * Indicates whether the iterated async iterable is done; meaning had either completed (by - * resolving a `{ done: true }` object - * [MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#done)) - * or threw an error (in which case the escorting `error` property will be set to it). + * Indicates whether the iterated async iterable has ended having no further values to yield, + * meaning either of: + * - it has completed (by resolving a `{ done: true }` object + * ([MDN docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#done))) + * - it had thrown an error (in which case the escorting `error` property will be set to + * that error). * * When `true`, the adjacent `value` property will __still be set__ to the last value seen - * until the moment of completing/erroring. + * before the moment of completing/erroring. * * Is always `false` for any plain value given instead of an async iterable. */