feat: add an exposed MaybeAsyncIterable helper generic type (#25)

Author: shtaif

src/MaybeAsyncIterable/index.ts

@@ -0,0 +1,26 @@
+export { MaybeAsyncIterable };
+
+/**
+ * Helper type that represents either a plain value or an async iterable of that value.
+ *
+ * This type is useful among else for typing props for components that can accept either a
+ * _"static" value_ or a _"changing" value_ (an async iterable) seamlessly.
+ *
+ * @example
+ * ```tsx
+ * import { It, type MaybeAsyncIterable } from 'react-async-iterators';
+ *
+ * function MyComponent(props: { values: MaybeAsyncIterable<string[]> }) {
+ *   return (
+ *     <ul>
+ *       <It value={props.values} initialValue={[]}>
+ *         {next => next.value.map((item, idx) =>
+ *           <li key={idx}>{item}</li>
+ *         )}
+ *       </It>
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+type MaybeAsyncIterable<T> = T | AsyncIterable<T>;

src/index.ts

@@ -2,6 +2,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';
+import { type MaybeAsyncIterable } from './MaybeAsyncIterable/index.js';
 
 export {
   useAsyncIter,
@@ -13,4 +14,5 @@ export {
   type FixedRefFormattedIterable,
   useAsyncIterState,
   type AsyncIterStateResult,
+  type MaybeAsyncIterable,
 };