@@ -9,10 +9,13 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableSubject
9
9
* is provided back __wrapped as an async iterable__.
10
10
*
11
11
* This hook allows a component to declare and manage a piece of state while easily letting it control
12
- * what area(s) specifically within the UI would be bound to it (will re-render in reaction to changes in it) -
13
- * combined for example with one or more {@link Iterate `<Iterate>`}s.
12
+ * what area(s) specifically within the UI should be bound to it (should re-render in reaction to changes
13
+ * in it) - combined for example with one or more {@link Iterate `<Iterate>`}s.
14
14
*
15
+ * @example
15
16
* ```tsx
17
+ * // Quick usage:
18
+ *
16
19
* import { useAsyncIterState, Iterate } from 'async-react-iterators';
17
20
*
18
21
* function MyForm() {
@@ -27,24 +30,56 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableSubject
27
30
*
28
31
* Greetings, <Iterate>{firstNameIter}</Iterate> <Iterate>{lastNameIter}</Iterate>
29
32
* </div>
30
- * )
33
+ * );
31
34
* }
32
35
* ```
33
36
*
37
+ * ---
38
+ *
34
39
* This is unlike vanila `React.useState` which simply re-renders the entire component. Instead,
35
40
* `useAsyncIterState` helps confine UI updates as well as facilitate layers of sub-components that pass
36
41
* actual async iterables across one another as props, skipping typical cascading re-renderings down to
37
42
* __only the inner-most leafs__ of the UI tree.
38
43
*
39
- * The returned async iterable is sharable; it can be iterated by multiple consumers concurrently
40
- * (e.g multiple {@link Iterate `<Iterate>`}s) all see the same yields at the same time.
44
+ * The returned async iterable contains a `.current.value` property which shows the current up to date
45
+ * state value at all times. Use this any case you just need to read the immediate current state rather
46
+ * than directly rendering it, since for rendering you may simply async-iterate it.
47
+ *
48
+ * @example
49
+ * ```tsx
50
+ * // Use the state iterable's `.current.value` property to read the immediate current state:
51
+ *
52
+ * import { useAsyncIterState } from 'async-react-iterators';
53
+ *
54
+ * function MyForm() {
55
+ * const [firstNameIter, setFirstName] = useAsyncIterState<string>();
56
+ * const [lastNameIter, setLastName] = useAsyncIterState<string>();
57
+ *
58
+ * return (
59
+ * <form
60
+ * onSubmit={() => {
61
+ * const firstName = firstNameIter.current.value;
62
+ * const lastName = lastNameIter.current.value;
63
+ * // submit `firstName` and `lastName`...
64
+ * }}
65
+ * >
66
+ * <>...</>
67
+ * </form>
68
+ * );
69
+ * }
70
+ * ```
71
+ *
72
+ * The returned async iterable is a shared iterable - can be iterated by multiple consumers simultaneously
73
+ * (e.g multiple {@link Iterate `<Iterate>`}s) and each would pick up the same yielded values and at the
74
+ * same time.
41
75
*
42
76
* The returned async iterable is automatically closed on host component unmount.
43
77
*
78
+ * ---
79
+ *
44
80
* @template TVal the type of state to be set and yielded by returned iterable.
45
81
*
46
- * @returns a stateful async iterable and a function with which to yield an update, both maintain stable
47
- * references across re-renders.
82
+ * @returns a stateful async iterable and a function with which to yield an update, both maintain stable references across re-renders.
48
83
*
49
84
* @see {@link Iterate `<Iterate>` }
50
85
*/
@@ -72,12 +107,26 @@ function useAsyncIterState<TVal>(): AsyncIterStateResult<TVal> {
72
107
}
73
108
74
109
/**
75
- * The pair of stateful async iterable and a function with which to yield an update .
110
+ * A pair of stateful async iterable and a function which modifies the state and yields the updated value .
76
111
* Returned from the {@link useAsyncIterState `useAsyncIterState`} hook.
77
112
*
78
113
* @see {@link useAsyncIterState `useAsyncIterState` }
79
114
*/
80
115
type AsyncIterStateResult < TVal > = [
116
+ /**
117
+ * A stateful async iterable which yields every updated value following a state update.
118
+ *
119
+ * Includes a `.current.value` property which shows the current up to date state value at all times.
120
+ *
121
+ * This is a shared async iterable - all iterators obtained from it share the same source values,
122
+ * meaning multiple iterators can be consumed (iterated) simultaneously, each one picking up the
123
+ * same values as others the moment they were generated through state updates.
124
+ */
81
125
values : AsyncIterableSubject < TVal > ,
126
+
127
+ /**
128
+ * A function which modifies the state, causing the paired async iterable to yield the updated state
129
+ * value and immediately sets its `.current.value` property to the latest state.
130
+ */
82
131
setValue : ( newValue : TVal ) => void ,
83
132
] ;
0 commit comments