first code for new useAsyncIterState hook

Author: shtaif

package.json

@@ -56,6 +56,7 @@
     "@eslint/js": "^9.17.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
+    "@types/lodash-es": "^4.17.12",
     "@types/node": "^22.10.2",
     "@types/react": "^18.2.47",
     "@types/react-dom": "^18.0.11",
@@ -66,6 +67,7 @@
     "eslint-config-prettier": "^9.1.0",
     "globals": "^15.13.0",
     "jsdom": "^25.0.1",
+    "lodash-es": "^4.17.21",
     "prettier": "^3.4.2",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.18.0",

pnpm-lock.yaml

@@ -0,0 +1,100 @@
+import { it, describe, expect, afterEach } from 'vitest';
+import { gray } from 'colorette';
+import { range } from 'lodash-es';
+import { renderHook, cleanup as cleanupMountedReactTrees, act } from '@testing-library/react';
+import { useAsyncIterState } from '../../src/index.js';
+import { asyncIterToArray } from '../utils/asyncIterToArray.js';
+import { asyncIterTake } from '../utils/asyncIterTake.js';
+import { pipe } from '../utils/pipe.js';
+
+afterEach(() => {
+  cleanupMountedReactTrees();
+});
+
+describe('`useAsyncIterState` hook', () => {
+  it(gray('The returned iterable can be async-iterated upon successfully'), async () => {
+    const [values, setValue] = renderHook(() => useAsyncIterState<string>()).result.current;
+
+    const valuesToSet = ['a', 'b', 'c'];
+
+    const collectPromise = pipe(values, asyncIterTake(valuesToSet.length), asyncIterToArray);
+
+    for (const value of valuesToSet) {
+      await act(() => setValue(value));
+    }
+
+    expect(await collectPromise).toStrictEqual(['a', 'b', 'c']);
+  });
+
+  it(
+    gray(
+      'When hook is unmounted, all outstanding yieldings of the returned iterable resolve to "done"'
+    ),
+    async () => {
+      const renderedHook = renderHook(() => useAsyncIterState<string>());
+      const [values] = renderedHook.result.current;
+
+      const [collectPromise1, collectPromise2] = range(2).map(() => asyncIterToArray(values));
+
+      renderedHook.unmount();
+
+      const collections = await Promise.all([collectPromise1, collectPromise2]);
+      expect(collections).toStrictEqual([[], []]);
+    }
+  );
+
+  it(
+    gray(
+      'After setting some values followed by unmounting the hook, the pre-unmounting values go through while further values pulled from the returned iterable are always "done"'
+    ),
+    async () => {
+      const renderedHook = renderHook(() => useAsyncIterState<string>());
+      const [values, setValue] = renderedHook.result.current;
+
+      const [collectPromise1, collectPromise2] = range(2).map(() => asyncIterToArray(values));
+
+      await act(() => setValue('a'));
+
+      renderedHook.unmount();
+
+      const collections = await Promise.all([collectPromise1, collectPromise2]);
+      expect(collections).toStrictEqual([['a'], ['a']]);
+    }
+  );
+
+  it(
+    gray(
+      'After the hook is unmounted, any further values pulled from the returned iterable are always "done"'
+    ),
+    async () => {
+      const renderedHook = renderHook(() => useAsyncIterState<string>());
+      const [values] = renderedHook.result.current;
+
+      renderedHook.unmount();
+
+      const collections = await Promise.all(range(2).map(() => asyncIterToArray(values)));
+      expect(collections).toStrictEqual([[], []]);
+    }
+  );
+
+  it(
+    gray(
+      "The returned iterable's values are each shared between all its parallel consumers so that each receives all the values from the start of consumption and onwards"
+    ),
+    async () => {
+      const [values, setValue] = renderHook(() => useAsyncIterState<string>()).result.current;
+
+      const consumeStacks: string[][] = [];
+
+      for (const [i, value] of ['a', 'b', 'c'].entries()) {
+        consumeStacks[i] = [];
+        (async () => {
+          for await (const v of values) consumeStacks[i].push(v);
+        })();
+        await act(() => setValue(value));
+      }
+
+      expect(consumeStacks).toStrictEqual([['a', 'b', 'c'], ['b', 'c'], ['c']]);
+    }
+  );
+});

spec/tests/useAsyncIterState.spec.tsx

@@ -0,0 +1,45 @@
+export { asyncIterTake };
+
+function asyncIterTake<T>(count: number): (src: AsyncIterable<T>) => AsyncIterable<T> {
+  return sourceIter => {
+    let iterator: AsyncIterator<T>;
+    let remainingCount = count;
+    let closed = false;
+
+    return {
+      [Symbol.asyncIterator]: () => ({
+        async next() {
+          if (closed) {
+            return { done: true, value: undefined };
+          }
+
+          iterator ??= sourceIter[Symbol.asyncIterator]();
+
+          if (remainingCount === 0) {
+            closed = true;
+            await iterator.return?.();
+            return { done: true, value: undefined };
+          }
+
+          remainingCount--;
+          const next = await iterator.next();
+
+          if (next.done) {
+            closed = true;
+            return { done: true, value: undefined };
+          }
+
+          return next;
+        },
+
+        async return() {
+          if (!closed) {
+            closed = true;
+            await iterator?.return?.();
+          }
+          return { done: true, value: undefined };
+        },
+      }),
+    };
+  };
+}

spec/utils/asyncIterTake.ts

@@ -1,9 +1,9 @@
 export { asyncIterToArray };
 
 async function asyncIterToArray<T>(source: AsyncIterable<T>): Promise<T[]> {
-  const values: T[] = [];
+  const collected: T[] = [];
   for await (const value of source) {
-    values.push(value);
+    collected.push(value);
   }
-  return values;
+  return collected;
 }

spec/utils/asyncIterToArray.ts

@@ -0,0 +1,24 @@
+export { promiseWithResolvers, type PromiseWithResolvers };
+
+const promiseWithResolvers: <T>() => PromiseWithResolvers<T> =
+  'withResolvers' in Promise
+    ? () => Promise.withResolvers()
+    : /**
+       * A ponyfill for the [`Promise.withResolvers`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers) helper
+       * @returns A pending {@link PromiseWithResolvers} instance for use
+       */
+      function promiseWithResolversPonyfill<T>(): PromiseWithResolvers<T> {
+        let resolve!: PromiseWithResolvers<T>['resolve'];
+        let reject!: PromiseWithResolvers<T>['reject'];
+        const promise = new Promise<T>((res, rej) => {
+          resolve = res;
+          reject = rej;
+        });
+        return { promise, resolve, reject };
+      };
+
+type PromiseWithResolvers<T> = {
+  promise: Promise<T>;
+  resolve(value: T): void;
+  reject(reason?: unknown): void;
+};

src/common/promiseWithResolvers.ts

@@ -1,6 +1,7 @@
 import { useAsyncIter, type IterationResult } from './useAsyncIter/index.js';
 import { Iterate, type IterateProps } from './Iterate/index.js';
 import { iterateFormatted, type FixedRefFormattedIterable } from './iterateFormatted//index.js';
+import { useAsyncIterState, type AsyncIterStateResult } from './useAsyncIterState/index.js';
 
 export {
   useAsyncIter,
@@ -9,4 +10,6 @@ export {
   type IterateProps,
   iterateFormatted,
   type FixedRefFormattedIterable,
+  useAsyncIterState,
+  type AsyncIterStateResult,
 };

src/index.ts

@@ -0,0 +1,25 @@
+import { promiseWithResolvers } from '../common/promiseWithResolvers.js';
+
+export { IterableChannel };
+
+class IterableChannel<TVal> {
+  #isClosed = false;
+  #nextIteration = promiseWithResolvers<IteratorResult<TVal, void>>();
+  iterable = {
+    [Symbol.asyncIterator]: () => ({
+      next: () => this.#nextIteration.promise,
+    }),
+  };
+
+  put(value: TVal): void {
+    if (!this.#isClosed) {
+      this.#nextIteration.resolve({ done: false, value });
+      this.#nextIteration = promiseWithResolvers();
+    }
+  }
+
+  close(): void {
+    this.#isClosed = true;
+    this.#nextIteration.resolve({ done: true, value: undefined });
+  }
+}

src/useAsyncIterState/IterableChannel.ts

@@ -0,0 +1,32 @@
+import { useEffect, useRef } from 'react';
+import { IterableChannel } from './IterableChannel.js';
+
+export { useAsyncIterState, type AsyncIterStateResult };
+
+/**
+ * ... ... ...
+ */
+function useAsyncIterState<TVal>(): AsyncIterStateResult<TVal> {
+  const ref = useRef<{
+    channel: IterableChannel<TVal>;
+    result: AsyncIterStateResult<TVal>;
+  }>();
+
+  if (!ref.current) {
+    const channel = new IterableChannel<TVal>();
+    ref.current = {
+      channel,
+      result: [channel.iterable, newVal => channel.put(newVal)],
+    };
+  }
+
+  const { channel, result } = ref.current;
+
+  useEffect(() => {
+    return () => channel.close();
+  }, []);
+
+  return result;
+}
+
+type AsyncIterStateResult<TVal> = [AsyncIterable<TVal, void, void>, (newValue: TVal) => void];