Skip to content

Commit 675331f

Browse files
authored
docs(useAsyncIterState): missing documentations for the state iterable's added current value property (#42)
1 parent 28a89f7 commit 675331f

File tree

2 files changed

+74
-8
lines changed

2 files changed

+74
-8
lines changed

src/useAsyncIterState/IterableChannel.ts

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,25 @@ class IterableChannel<T> {
4040
};
4141
}
4242

43+
/**
44+
* A stateful async iterable which will yield every updated value following an update. Includes a
45+
* `.current.value` property which shows the current up to date state value.
46+
*
47+
* This is a shared async iterable - all iterators obtained from it share the same source values,
48+
* meaning that multiple iterators can be consumed (iterated) simultaneously and each one would pick up
49+
* the same values as others the moment they were generated through state updates.
50+
*/
4351
type AsyncIterableSubject<T> = {
52+
/**
53+
* A React Ref-like object whose inner `current` property shows the most up to date state value.
54+
*/
4455
value: MutableRefObject<T | undefined>;
56+
57+
/**
58+
* Returns an async iterator to iterate over. All iterators returned by this share the same source
59+
* values - they can be iterated by multiple consumers simultaneously and each would pick up the
60+
* same values as others the moment they were generated.
61+
*/
4562
[Symbol.asyncIterator](): {
4663
next(): Promise<IteratorResult<T, void>>;
4764
return(): Promise<IteratorReturnResult<void>>;

src/useAsyncIterState/index.ts

Lines changed: 57 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,13 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableSubject
99
* is provided back __wrapped as an async iterable__.
1010
*
1111
* 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.
1414
*
15+
* @example
1516
* ```tsx
17+
* // Quick usage:
18+
*
1619
* import { useAsyncIterState, Iterate } from 'async-react-iterators';
1720
*
1821
* function MyForm() {
@@ -27,24 +30,56 @@ export { useAsyncIterState, type AsyncIterStateResult, type AsyncIterableSubject
2730
*
2831
* Greetings, <Iterate>{firstNameIter}</Iterate> <Iterate>{lastNameIter}</Iterate>
2932
* </div>
30-
* )
33+
* );
3134
* }
3235
* ```
3336
*
37+
* ---
38+
*
3439
* This is unlike vanila `React.useState` which simply re-renders the entire component. Instead,
3540
* `useAsyncIterState` helps confine UI updates as well as facilitate layers of sub-components that pass
3641
* actual async iterables across one another as props, skipping typical cascading re-renderings down to
3742
* __only the inner-most leafs__ of the UI tree.
3843
*
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.
4175
*
4276
* The returned async iterable is automatically closed on host component unmount.
4377
*
78+
* ---
79+
*
4480
* @template TVal the type of state to be set and yielded by returned iterable.
4581
*
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.
4883
*
4984
* @see {@link Iterate `<Iterate>`}
5085
*/
@@ -72,12 +107,26 @@ function useAsyncIterState<TVal>(): AsyncIterStateResult<TVal> {
72107
}
73108

74109
/**
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.
76111
* Returned from the {@link useAsyncIterState `useAsyncIterState`} hook.
77112
*
78113
* @see {@link useAsyncIterState `useAsyncIterState`}
79114
*/
80115
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+
*/
81125
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+
*/
82131
setValue: (newValue: TVal) => void,
83132
];

0 commit comments

Comments
 (0)