feat: implement the new useAsyncIterMulti hook (#28)

Author: shtaif

spec/tests/useAsyncIterMulti.spec.ts

@@ -0,0 +1,9 @@
+export { asyncIterOf };
+
+function asyncIterOf<const T>(...values: T[]) {
+  return {
+    async *[Symbol.asyncIterator]() {
+      yield* values;
+    },
+  };
+}

spec/utils/asyncIterOf.ts

@@ -0,0 +1,38 @@
+import { identity } from './identity.js';
+
+export {
+  parseReactAsyncIterable,
+  reactAsyncIterSpecialInfoSymbol,
+  type ReactAsyncIterable,
+  type ReactAsyncIterSpecialInfo,
+};
+
+function parseReactAsyncIterable<T>(
+  value: AsyncIterable<T> & Partial<ReactAsyncIterable<unknown, T>>
+): {
+  baseIter: ReactAsyncIterSpecialInfo<unknown, T>['origSource'];
+  formatFn: ReactAsyncIterSpecialInfo<unknown, T>['formatFn'];
+} {
+  if (value[reactAsyncIterSpecialInfoSymbol]) {
+    const { origSource, formatFn } = value[reactAsyncIterSpecialInfoSymbol];
+    return {
+      baseIter: origSource,
+      formatFn: formatFn,
+    };
+  }
+  return {
+    baseIter: value,
+    formatFn: identity<T>,
+  };
+}
+
+const reactAsyncIterSpecialInfoSymbol = Symbol('reactAsyncIterSpecialInfoSymbol');
+
+type ReactAsyncIterable<TVal, TValFormatted> = AsyncIterable<TValFormatted, void, void> & {
+  [reactAsyncIterSpecialInfoSymbol]: ReactAsyncIterSpecialInfo<TVal, TValFormatted>;
+};
+
+type ReactAsyncIterSpecialInfo<TOrigVal, TFormattedVal> = {
+  origSource: AsyncIterable<TOrigVal>;
+  formatFn(value: TOrigVal, i: number): TFormattedVal;
+};

src/common/ReactAsyncIterable.ts

@@ -0,0 +1,18 @@
+import { useRef, type MutableRefObject } from 'react';
+
+export { useRefWithInitialValue };
+
+function useRefWithInitialValue<T = undefined>(initialValueFn: () => T): MutableRefObject<T> {
+  const isRefInitializedRef = useRef<boolean>();
+
+  const ref = useRef<T>();
+
+  if (!isRefInitializedRef.current) {
+    isRefInitializedRef.current = true;
+    ref.current = initialValueFn();
+  }
+
+  const refNonNull = ref as typeof ref & { current: T };
+
+  return refNonNull;
+}

src/common/hooks/useRefWithInitialValue.ts

@@ -0,0 +1,3 @@
+export { identity };
+
+const identity = <T>(val: T) => val;

src/common/identity.ts

@@ -3,5 +3,6 @@ import { type ExtractAsyncIterValue } from './ExtractAsyncIterValue.js';
 export { isAsyncIter };
 
 function isAsyncIter<T>(input: T): input is T & AsyncIterable<ExtractAsyncIterValue<T>> {
-  return typeof (input as any)?.[Symbol.asyncIterator] === 'function';
+  const inputAsAny = input as any;
+  return typeof inputAsAny?.[Symbol.asyncIterator] === 'function';
 }

src/common/isAsyncIter.ts

@@ -1,18 +1,26 @@
 import { useAsyncIter, type IterationResult } from './useAsyncIter/index.js';
+import { useAsyncIterMulti } from './useAsyncIterMulti/index.js';
 import { Iterate, type IterateProps } from './Iterate/index.js';
-import { iterateFormatted, type FixedRefFormattedIterable } from './iterateFormatted/index.js';
+import { iterateFormatted } from './iterateFormatted/index.js';
 import { useAsyncIterState, type AsyncIterStateResult } from './useAsyncIterState/index.js';
 import { type MaybeAsyncIterable } from './MaybeAsyncIterable/index.js';
+import { type ReactAsyncIterable } from './common/ReactAsyncIterable.js';
 
 export {
   useAsyncIter,
   type IterationResult,
+  useAsyncIterMulti,
   Iterate,
   Iterate as It,
   type IterateProps,
   iterateFormatted,
-  type FixedRefFormattedIterable,
   useAsyncIterState,
   type AsyncIterStateResult,
   type MaybeAsyncIterable,
+  type ReactAsyncIterable,
+
+  /**
+   * @deprecated use {@link ReactAsyncIterable `ReactAsyncIterable`} instead.
+   * */
+  type ReactAsyncIterable as FixedRefFormattedIterable,
 };

src/common/reactAsyncIterSpecialInfoSymbol.ts

@@ -1,14 +1,15 @@
 import {
   reactAsyncIterSpecialInfoSymbol,
+  type ReactAsyncIterable,
   type ReactAsyncIterSpecialInfo,
-} from '../common/reactAsyncIterSpecialInfoSymbol.js';
+} from '../common/ReactAsyncIterable.js';
 import { asyncIterSyncMap } from '../common/asyncIterSyncMap.js';
 import { isAsyncIter } from '../common/isAsyncIter.js';
 import { type ExtractAsyncIterValue } from '../common/ExtractAsyncIterValue.js';
 import { type useAsyncIter } from '../useAsyncIter/index.js'; // eslint-disable-line @typescript-eslint/no-unused-vars
 import { type Iterate } from '../Iterate/index.js'; // eslint-disable-line @typescript-eslint/no-unused-vars
 
-export { iterateFormatted, type FixedRefFormattedIterable };
+export { iterateFormatted };
 
 /**
  * An optional utility to format an async iterable's values inline right where its passing into
@@ -75,9 +76,7 @@ export { iterateFormatted, type FixedRefFormattedIterable };
 function iterateFormatted<TIn, TOut>(
   source: TIn,
   formatFn: (value: ExtractAsyncIterValue<TIn>, i: number) => TOut
-): TIn extends AsyncIterable<unknown>
-  ? FixedRefFormattedIterable<ExtractAsyncIterValue<TIn>, TOut>
-  : TOut;
+): TIn extends AsyncIterable<unknown> ? ReactAsyncIterable<ExtractAsyncIterValue<TIn>, TOut> : TOut;
 
 function iterateFormatted(
   source: unknown,
@@ -107,7 +106,3 @@ function iterateFormatted(
         },
   };
 }
-
-type FixedRefFormattedIterable<TVal, TValFormatted> = AsyncIterable<TValFormatted, void, void> & {
-  [reactAsyncIterSpecialInfoSymbol]: ReactAsyncIterSpecialInfo<TVal, TValFormatted>;
-};

src/index.ts

@@ -6,13 +6,13 @@ import { type ExtractAsyncIterValue } from '../common/ExtractAsyncIterValue.js';
 import {
   reactAsyncIterSpecialInfoSymbol,
   type ReactAsyncIterSpecialInfo,
-} from '../common/reactAsyncIterSpecialInfoSymbol.js';
+} from '../common/ReactAsyncIterable.js';
 import { type Iterate } from '../Iterate/index.js'; // eslint-disable-line @typescript-eslint/no-unused-vars
 import { type iterateFormatted } from '../iterateFormatted/index.js'; // eslint-disable-line @typescript-eslint/no-unused-vars
 
 export { useAsyncIter, type IterationResult };
 
-// TODO: The initial value can be given as a function, which the internal `useState` would invoke as it's defined to do. So the typings should take into account it possibly being a function and if that's the case then to extract its return type instead of using the function type itself
+// TODO: The initial values should be able to be given as functions, having them called once on mount
 
 /**
  * `useAsyncIter` hooks up a single async iterable value into your component and its lifecycle.
@@ -145,8 +145,9 @@ const useAsyncIter: {
       latestInputRef.current[reactAsyncIterSpecialInfoSymbol]?.origSource ?? latestInputRef.current;
 
     useMemo((): void => {
+      const prevSourceLastestVal = stateRef.current.value;
       stateRef.current = {
-        value: stateRef.current.value,
+        value: prevSourceLastestVal,
         pendingFirst: true,
         done: false,
         error: undefined,