>
ℹ️ As seen above, unless you require some more elaborate transformation than simply formatting values - it might be more ergonomic to use iterateFormatted vs manual compositions within React.useMemos - especially if you're having to transform multiple iterables.



Every call to iterateFormatted returns a _formatted_ versions of currenciesIter with some transparent metadata, which the library's consumers (like ) use to associate every transformed iterable with its original source iterable, and this way existing iteration states can be persisted properly. It's therefore safe to recreate and pass on formatted iterables from repeated calls to iterateFormatted across re-renders (as long the same source is used with it consistently).

State as an async iterable

As illustrated throughout this library and docs - when dealing with data in your app that's presented as an async iterable, an interesting pattern emerges; instead of a transition in app state traditionally sending down a cascading re-render through the entire tree of components underneath it to propagate the new state - your __async iterable__ objects can be distributed __once__ when the whole tree is first mounted, and new data is then communicated through them so it directly gets to the components that are concerned with displaying it, at the edges of the UI tree, re-rendering them exclusively and thus skipping all intermediaries.

The packaged useAsyncIterState hook can lend this paradigm to your __component state__. It's like a React.useState version that returns you _an async iterable of the state value instead of the state value_, paired with a setter function that causes the stateful iterable to yield the next states.

The stateful iterable may be distributed via props down through any number of component levels the same way you would with classic React state, and used in conjunction with or useAsyncIter, etc. wherever it has to be rendered.

In a glance, it's usage looks like this:

`tsx
import { useAsyncIterState, It } from 'react-async-iterators';

function MyCounter() {
const [countIter, setCount] = useAsyncIterState(0);

function handleIncrement() {
setCount(count => count + 1);
}

return (
<>
Current count: {countIter} {/ <- this is the ONLY thing re-rendering here! /}
Increment

);
}
`

The stateful iterable let's you access the current state any time via its .value.current property (see Async iterables with current values) so you may read it when you need to get only the current state alone, for example - as part of some side effect logic;

`tsx
// Using the state iterable's .value.current property to read the immediate current state:

import { useAsyncIterState, It } from 'react-async-iterators';

function MyForm() {
const [firstNameIter, setFirstName] = useAsyncIterState('');
const [lastNameIter, setLastName] = useAsyncIterState('');

return (
onSubmit={() => {
const firstName = firstNameIter.value.current;
const lastName = lastNameIter.value.current;
// submit firstName and lastName...
}}
>
Greetings, {firstNameIter} {lastNameIter}

{/ More content... /}

);
}
`

>
ℹ️ Remember that merely accessing .value.current will only get the current state at that point in time and is not meant for picking up future updates in it. To be in sync with current and future states, simply render the state iterable through a .



_Play with useAsyncIterState inside a StackBlitz playground:_

![Open in StackBlitz](https://stackblitz.com/edit/react-async-iterators-example-4?file=src%2FApp.tsx)

API

Iteration state properties breakdown

The following iteration state properties are common for all consumer utilities, with hooks - returned, with components - injected to their given render functions.

As detailed below, the types of these properties are affected by particular phases of the iteration process - see _Lifecycle phases_ for more info.

Components

$3

_Alias: _

The component (also exported as ) is used to format and render an async iterable (or a plain non-iterable value) directly onto a piece of UI.

Essentially, can be seen as a useAsyncIter hook in a component form.

`tsx
// In "simplified" form:

{myIter}


// In "render function" form:


{({ value, pendingFirst, done, error }) =>
// ...
}

`

$3

- value:
The source value to iterate over - an async iterable or a plain (non async iterable) value. The input value may be changed any time, starting a new iteration in the background, per Iteration lifecycle. If using the "simplified" form, value is ignored and the source value should be provided as children instead.

- initialValue:
An _optional_ starting value, defaults to undefined. Will be the value inserted into the child render function when first renders during mount and while it's pending first yield. You can pass an actual value, or a function that returns a value (which will call once during mounting).

- children:
A render function that is called for each step of the iteration, returning something to render out of it, with the current state object as the argument (see Iteration state properties breakdown). If using the "simplified" form instead - the source value should be directly passed as children and yielded values are rendered just as-are without any formatting on top.

$3

-
Care should be taken to avoid passing a constantly recreated iterable object across re-renders, e.g; by declaring it outside the component body or by controlling __when__ it should be recreated with React's useMemo.

$3

_Alias: _

The component (also exported as ) is used to combine and render any number of async iterables (or plain non-iterable values) directly onto a piece of UI.

It's similar to , only it works with any changeable number of async iterables or plain values instead of a single one. Essentially, can be seen as a useAsyncIterMulti hook in a component form.

`tsx
... /]}>
{([myIterNext, myOtherIterNext]) =>
// ...
}

`

$3

- values:
An array of values to iterate over simultaneously, which may include any mix of async iterables or plain (non async iterable) values. Source values may be added, removed or changed at any time and new iterations will be close and started accordingly as per Iteration lifecycle.

- initialValues:
An _optional_ array of initial values or functions that return initial values. The values here will be the starting points for all the async iterables from values (by corresponding array positions) while they are rendered by the children render function __for the first time__ and for each while it is __pending its first yield__. Async iterables from values that have no initial value corresponding to them will assume undefined as initial value.

- defaultInitialValue:
An _optional_ default starting value for every new async iterable in values if there is no corresponding one for it in the initialValues prop, defaults to undefined. You can pass an actual value, or a function that returns a value (which the hook will call for every new iterable added).

- children:
A render function that is called on every progression in any of the running iterations, returning something to render for them. The function is called with an array of the combined iteration state objects of all sources currently given by the values prop (see Iteration state properties breakdown).

$3

-
Care should be taken to avoid passing constantly recreated async iterables across re-renders, e.g; by declaring iterables outside the component body or by controlling __when__ iterables should be recreated with React's useMemo.

Hooks

$3

useAsyncIter hooks up a single async iterable value to your component and its lifecycle.

`tsx
const next = useAsyncIter(myIter, 'initial_value');

next.value;
next.pendingFirst;
next.done;
next.error;
`

$3

- value:
The source value to iterate over - an async iterable or a plain (non async iterable) value. The input value may be changed any time, starting a new iteration in the background, per Iteration lifecycle.

- initialValue:
An _optional_ starting value for the hook to return prior to the ___first yield___ of the ___first given___ async iterable, defaults to undefined. You can pass an actual value, or a function that returns a value (which the hook will call once during mounting).

$3

The iteration state object with properties reflecting the current state of the iterated async iterable or plain value provided via value (see Iteration state properties breakdown).

$3

-
may be preferable over the useAsyncIter counterpart typically as the UI area it re-renders within a component tree can be confined expressively to the necessary minimum, saving any other unrelated elements from re-evaluation. On the other hand, useAsyncIter being a hook must re-render the entire component's output for every new value.

-
Care should be taken to avoid passing a constantly recreated iterable object across re-renders, e.g; by declaring it outside the component body or by controlling __when__ it should be recreated with React's useMemo.

$3

useAsyncIterMulti hooks up multiple async iterable (or plain) values to your component and its lifecycle.

It's similar to useAsyncIter, only it works with any number of async iterables or plain values instead of a single one.

`tsx
const nextStates = useAsyncIterMulti(iters);

// or also:

const [nextNum, nextStr, nextArr] = useAsyncIterMulti([numberIter, stringIter, arrayIter], {
initialValues: [0, '', []]
});
`

$3

- values:
An array of values to iterate over simultaneously, which may include any mix of async iterables or plain (non async iterable) values. Source values may be added, removed or changed at any time and new iterations will be close and started accordingly as per Iteration lifecycle.

- opts:
An _optional_ object with properties:

- initialValues:
An _optional_ array of initial values or functions that return initial values. The values will be the starting points for all the async iterables from values (by corresponding array positions) __for the first time__ and for each while it is __pending its first yield__. For async iterables from values that have no corresponding item here the provided opts.defaultInitialValue will be used as fallback.

- defaultInitialValue:
An _optional_ default starting value for every new async iterable in values if there is no corresponding one for it in opts.initialValues, defaults to undefined. You can pass an actual value, or a function that returns a value (which the hook will call for every new iterable added).

$3

An array of objects with up-to-date information about each input's current value, completion status, and more - corresponding to the order by which they appear on values (see Iteration state properties breakdown).

$3

-
Care should be taken to avoid passing constantly recreated async iterables across re-renders, e.g; by declaring iterables outside the component body or by controlling __when__ iterables should be recreated with React's useMemo.



$3

Basically like React.useState, only that the value is provided back __wrapped in an async iterable__.

This hook allows a component to declare and manage a piece of state as an async iterable thus letting you easily control what specific places in the app UI tree should be bound to it, re-rendering in reaction to its changes (if used in conjunction with for example).

`tsx
const [valueIter, setValue] = useAsyncIterState(initialValue);

function handleChange() {
setValue(valueIter.value.current + 1);
// or:
setValue(value => value + 1);
}

{valueIter}

function handleValueSubmit() {
// use valueIter.value.current to get the current state immediately
// (e.g, as part of some side effect logic)
submitMyValue({ value: valueIter.value.current });
}
`

$3

- initialValue:
Any _optional_ starting value for the state iterable's .value.current property, defaults to undefined. You can pass an actual value, or a function that returns a value (which the hook will call once during mounting).

$3

A stateful async iterable with accessible current value and a function for yielding an update. The returned async iterable is a shared iterable such that multiple simultaneous consumers (e.g multiple s) all pick up the same yields at the same times. The setter function, likeReact.useState's setter, can be provided either the next state directly, or a function that calculates it from the previous state.

$3

>
ℹ️ The returned state iterable also contains a .value.current property which shows the current up to date state value at any time. Use this any time you need to read the immediate current state (e.g as part of side effects). Otherwise, to display its value and future ones to a user simply render it with things like /, useAsyncIter, etc - more info at Async iterables with current values.



>
ℹ️ The returned async iterable and setter function both maintain stable references across re-renders so are effective for use within React's useMemo or useEffect and their dependency lists.



$3

Hook that takes a source async iterable and returns a version of it that will always initialize up to
just one single instance of the source at any point in time, sharing it to any number of simultaneous consumers
the result iterable might have (e.g multiple s).

`tsx
const sharedIter = useSharedAsyncIter(iter);
// ...
`

Any number of iterators for the resulting iterable you create and consume simultaneously will only ever
create a single iterator internally for the original source and distribute every yielded value, completion or
possible error among each of them.

In a _reference-counting_ fashion, only when the last remaining iterator is closed will the shared
source iterator be finally closed as well, disposing of resources it held, after which instantiating a new iterator will restart the cycle. This way, async iterables that instantiate server connections, streams, etc. - can easily be consumed or rendered concurrently by multiple components without possibly opening duplicate resources or other undesired effects, depending on the way these source iterables were constructed.

If given a plain non-iterable value, this hook would seamlessly return it as-is without additional effect.

$3

- value:
The source async iterable or plain value.

$3

A "_shared_" version of the source async iterable or the source value itself in case it was a plain value.

$3

>
ℹ️ Repeated calls with the same source iterable will return the same memoized result iterable, as well as calls with iterateFormatted-returned iterables based of the same source for that matter.



Utils

$3

A utility to inline-format an async iterable's values before passed into another consuming component.

Can be thought of as mapping an async iterable before being rendered/passed over in the same way you would commonly .map(...) an array before rendering/passing it over. More details in Formatting values.

`tsx
iterateFormatted(myIter, (value, idx) => {
// return a formatted value here...
})
`

`tsx
// With some given async-iter-receiving