@repeaterjs/react-hooks

React hooks for working with async iterators/generators.

These functions are implemented with repeaters. For more information about repeaters, visit repeater.js.org.

Installation

npm install @repeaterjs/react-hooks

yarn add @repeaterjs/react-hooks

API

`useResult`

declare function useResult<T, TDeps extends any[]>(
  callback: (deps: AsyncIterableIterator<TDeps>) => AsyncIterableIterator<T>,
  deps?: TDeps,
): IteratorResult<T> | undefined;

import {useResult} from "@repeaterjs/react-hooks";

const result = useResult(async function *() {
  /* ... */
});

callback is a function which returns an async iterator, usually an async generator function. The callback is called when the component initializes and the returned iterator updates the component whenever it produces results. useResult returns an IteratorResult, an object of type {value: T, done: boolean}, where T is the type of the produced values, and done indicates whether the iterator has returned. The first return value from this hook will be undefined, indicating that the iterator has yet to produce any values.

function Timer() {
  const result = useResult(async function*() {
    let i = 0;
    while (true) {
      yield i++
      await new Promise((resolve) => setTimeout(resolve, 1000));
    }
  });

  return <div>Seconds: {result && result.value}</div>;
}

Similar to the useEffect hook, useResult accepts an array of dependencies as a second argument. However, rather than being referenced via closure, the dependencies are passed into the callback as an async iterator which updates whenever any of the dependencies change. We pass the dependencies in manually because callback is only called once, and dependencies referenced via closure become stale as the component updates.

function ProductDetail({productId}) {
  const result = useResult(async function *(deps) {
    for await (const [productId] of deps) {
      const data = await fetchProductData(productId);
      yield data.description;
    }
  }, [productId]);

  if (result == null) {
    return <div>Loading...</div>;
  }

  return <div>Description: {result.value}</div>;
}

`useValue`

declare function useValue<T, TDeps extends any[]>(
  callback: (deps: AsyncIterableIterator<TDeps>) => AsyncIterableIterator<T>,
  deps?: TDeps,
): T | undefined;

import {useValue} from "@repeaterjs/react-hooks";

const value = useValue(async function *() {
  /* ... */
});

Similar to useResult, except the IteratorResult’s value is returned rather than the IteratorResult object itself. Prefer useValue over useResult when you don’t need to distinguish between whether values were yielded or returned.

`useAsyncIter`

declare function useAsyncIter<T, TDeps extends any[]>(
  callback: (deps: AsyncIterableIterator<TDeps>) => AsyncIterableIterator<T>,
  deps: TDeps = ([] as unknown) as TDeps,
): AsyncIterableIterator<T>;

import {useAsyncIter} from "@repeaterjs/react-hooks";

function MyComponent() {
  const iter = useAsyncIter(async function *() {
    /* ... */
  });
  /* ... */
}

Similar to useResult and useValue, except that useAsyncIter returns the async iterator itself rather than consuming it. The returned async iterator can be referenced via closure in further useResult calls. Prefer useAsyncIter over useResult or useValue when you want to use an async iterator without updating each time a value is produced.

const konami = ["ArrowUp", "ArrowUp", "ArrowDown", "ArrowDown", "ArrowLeft", "ArrowRight", "ArrowLeft", "ArrowRight", "b", "a"];
function Cheats() {
  const keys = useAsyncIter(() => {
    return new Repeater(async (push, stop) => {
      const listener = (ev) => push(ev.key);
      window.addEventListener("keyup", listener);
      await stop;
      window.removeEventListener("keyup", listener);
    });
  });

  const result = useResult(async function *() {
    let i = 0;
    yield konami[i];
    for await (const key of keys) {
      if (key === konami[i]) {
        i++;
      } else {
        i = 0;
      }

      if (i < konami.length) {
        yield konami[i];
      } else {
        return "Cheats activated";
      }
    }
  });

  if (result == null) {
    return null;
  } else if (result.done) {
    return <div>🎉 {result.value} 🎉</div>;
  }

  return <div>Next key: {result.value}</div>;
}

`useRepeater`

declare function useRepeater<T>(
  buffer?: RepeaterBuffer<T>,
): [Repeater<T>, Push<T>, Stop];

import { useRepeater } from "@repeaterjs/react-hooks";
import { SlidingBuffer } from "@repeaterjs/repeater";

function MyComponent() {
  const [repeater, push, stop] = useRepeater(new SlidingBuffer(10));
  /* ... */
}

Creates a repeater which can be used in useResult callbacks. push and stop can be used in later callbacks to update the repeater. For more information about the push and stop functions or the buffer argument, refer to the repeater.js docs.

function MarkdownEditor() {
  const [inputs, push] = useRepeater();
  const result = useResult(async function*() {
    const md = new Remarkable();
    for await (const input of inputs) {
      yield md.render(input);
    }
  });
  return (
    <div>
      <h3>Input</h3>
      <textarea
        defaultValue="Hello, **world**!"
        onChange={(ev) => push(ev.target.value)}
      />
      <h3>Output</h3>
      <div dangerouslySetInnnerHTML={{ __html: result && result.value }} />
    </div>
  );
}