docs(zip): refine signature and docs

Author: lambdalisue

async/zip.ts

@@ -1,40 +1,58 @@
 /**
  * Zips multiple iterables into a single iterable.
  *
+ * The resulting iterable will yield arrays of elements from the input iterables.
+ * The first array will contain the first element of each input iterable, the second array will contain the second element of each input iterable, and so on.
+ *
+ * If the input iterables have different lengths, the resulting iterable will stop when the shortest input iterable is exhausted.
+ * The remaining elements from the longer input iterables will be ignored.
+ *
+ * Use {@linkcode https://jsr.io/@core/iterutil/async/chain chain} to chain iterables.
+ * Use {@linkcode https://jsr.io/@core/iterutil/async/enumerate enumerate} to zip with indices.
+ * Use {@linkcode https://jsr.io/@core/iterutil/zip zip} to zip iterables synchronously.
+ *
  * @param iterables The iterables to zip.
  * @returns The zipped iterable.
  *
  * @example
  * ```ts
  * import { zip } from "@core/iterutil/async/zip";
  *
- * const iter = zip([1, 2, 3], ["a", "b", "c"]);
- * console.log(await Array.fromAsync(iter)); // [[1, "a"], [2, "b"], [3, "c"]]
+ * const iter = zip(
+ *   [1, 2, 3],
+ *   ["a", "b", "c"],
+ *   [true, false, true],
+ * );
+ * console.log(await Array.fromAsync(iter)); // [[1, "a", true], [2, "b", false], [3, "c", true]]
  * ```
  */
 export async function* zip<
-  U extends (Iterable<unknown> | AsyncIterable<unknown>)[],
+  U extends readonly [
+    Iterable<unknown> | AsyncIterable<unknown>,
+    Iterable<unknown> | AsyncIterable<unknown>,
+    ...(Iterable<unknown> | AsyncIterable<unknown>)[],
+  ],
 >(
   ...iterables: U
 ): AsyncIterable<Zip<U>> {
-  const its = iterables.map((iterable) =>
-    Symbol.iterator in iterable
-      ? iterable[Symbol.iterator]()
-      : iterable[Symbol.asyncIterator]()
+  const iterators = iterables.map((it) =>
+    Symbol.iterator in it ? it[Symbol.iterator]() : it[Symbol.asyncIterator]()
   );
   while (true) {
-    const rs = await Promise.all(its.map((it) => it.next()));
-    if (rs.find(({ done }) => !!done)) {
+    const results = await Promise.all(iterators.map((it) => it.next()));
+    if (results.find(({ done }) => !!done)) {
       break;
     }
-    yield rs.map(({ value }) => value) as Zip<U>;
+    yield results.map(({ value }) => value) as Zip<U>;
   }
 }
 
 /**
  * @internal
  */
-export type Zip<T extends (Iterable<unknown> | AsyncIterable<unknown>)[]> = {
+export type Zip<
+  T extends readonly (Iterable<unknown> | AsyncIterable<unknown>)[],
+> = {
   [P in keyof T]: T[P] extends Iterable<infer U> ? U
     : T[P] extends AsyncIterable<infer U> ? U
     : never;

zip.ts

@@ -1,33 +1,53 @@
 /**
  * Zips multiple iterables into a single iterable.
  *
+ * The resulting iterable will yield arrays of elements from the input iterables.
+ * The first array will contain the first element of each input iterable, the second array will contain the second element of each input iterable, and so on.
+ *
+ * If the input iterables have different lengths, the resulting iterable will stop when the shortest input iterable is exhausted.
+ * The remaining elements from the longer input iterables will be ignored.
+ *
+ * Use {@linkcode https://jsr.io/@core/iterutil/chain chain} to chain iterables.
+ * Use {@linkcode https://jsr.io/@core/iterutil/enumerate enumerate} to zip with indices.
+ * Use {@linkcode https://jsr.io/@core/iterutil/async/zip async zip} to zip asynchronously.;w
+ *
  * @param iterables The iterables to zip.
  * @returns The zipped iterable.
  *
  * @example
  * ```ts
  * import { zip } from "@core/iterutil/zip";
  *
- * const iter = zip([1, 2, 3], ["a", "b", "c"]);
- * console.log(Array.from(iter)); // [[1, "a"], [2, "b"], [3, "c"]]
+ * const iter = zip(
+ *   [1, 2, 3],
+ *   ["a", "b", "c"],
+ *   [true, false, true],
+ * );
+ * console.log(Array.from(iter)); // [[1, "a", true], [2, "b", false], [3, "c", true]]
  * ```
  */
-export function* zip<U extends Iterable<unknown>[]>(
+export function* zip<
+  U extends readonly [
+    Iterable<unknown>,
+    Iterable<unknown>,
+    ...Iterable<unknown>[],
+  ],
+>(
   ...iterables: U
 ): Iterable<Zip<U>> {
-  const its = iterables.map((iterable) => iterable[Symbol.iterator]());
+  const iterators = iterables.map((it) => it[Symbol.iterator]());
   while (true) {
-    const rs = its.map((it) => it.next());
-    if (rs.find(({ done }) => !!done)) {
+    const results = iterators.map((it) => it.next());
+    if (results.find(({ done }) => !!done)) {
       break;
     }
-    yield rs.map(({ value }) => value) as Zip<U>;
+    yield results.map(({ value }) => value) as Zip<U>;
   }
 }
 
 /**
  * @internal
  */
-export type Zip<T extends Iterable<unknown>[]> = {
+export type Zip<T extends readonly Iterable<unknown>[]> = {
   [P in keyof T]: T[P] extends Iterable<infer U> ? U : never;
 };