feat: add duplicate method to both iterables

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added:
   - Added `mapKey` method to both iterables
   - Added `mapValue` method to both iterables
+  - Added `duplicate` method to both iterables
 
 ### Changed:
   - Improved types of `toObject` and `toMap` methods

docs/polyethylene.md

@@ -46,4 +46,5 @@ The entry point for this library is the [Poly](./polyethylene.poly.md) namespace
 |  [IndexedReducer](./polyethylene.indexedreducer.md) | A function that receives an accumulated result, an element of an iteration, and returns a new accumulated result for the next call or as a final return value. |
 |  [IndexedRunnable](./polyethylene.indexedrunnable.md) | A function that receives an object (<code>elem</code>) and its <code>index</code> in the iteration and doesn't return anything |
 |  [IndexedTypePredicate](./polyethylene.indexedtypepredicate.md) | A function that receives an object (<code>elem</code>) and its <code>index</code> in the iteration and returns a <code>boolean</code> value indicating if <code>elem</code> is of the generic type <code>U</code> |
+|  [Tuple](./polyethylene.tuple.md) | A tuple of <code>N</code> elements of type <code>T</code>. |
 

docs/polyethylene.polyasynciterable.duplicate.md

@@ -0,0 +1,32 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [polyethylene](./polyethylene.md) &gt; [PolyAsyncIterable](./polyethylene.polyasynciterable.md) &gt; [duplicate](./polyethylene.polyasynciterable.duplicate.md)
+
+## PolyAsyncIterable.duplicate() method
+
+Returns a tuple containing `num` iterables that will yield independent copies of the elements yielded by `this`<!-- -->.
+
+**Signature:**
+
+```typescript
+duplicate<N extends number>(num: N): Tuple<PolyAsyncIterable<T>, N>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  num | N | the number of copies to be returned |
+
+**Returns:**
+
+[Tuple](./polyethylene.tuple.md)<!-- -->&lt;[PolyAsyncIterable](./polyethylene.polyasynciterable.md)<!-- -->&lt;T&gt;, N&gt;
+
+An array of `num` elements containing independent copies of this iterable
+
+## Remarks
+
+Note that, as with every other method of this class, this instance is unusable after calling this method.
+
+In order to provide a truly independent iteration for all returned iterables, a buffer is kept, which can grow as big as the whole iteration in certain circumstances. The buffer is filled as fast as the fastest iterable requests new items, and emptied as fast as the slowest iterable consumes those items.
+

docs/polyethylene.polyasynciterable.md

@@ -42,6 +42,7 @@ The constructor for this class is marked as internal. Third-party code should no
 |  [drop(num)](./polyethylene.polyasynciterable.drop.md) |  | Return a new iteration that skips the first <code>num</code> elements. If there were less than <code>num</code> elements in the iteration, no elements are yielded. |
 |  [dropLast(num)](./polyethylene.polyasynciterable.droplast.md) |  | Return a new iteration that skips the last <code>num</code> elements. If there were less than <code>num</code> elements in the iteration, no elements are yielded. |
 |  [dropWhile(func)](./polyethylene.polyasynciterable.dropwhile.md) |  | Return a new iteration that skips the first few elements for which <code>func(element)</code> returns <code>true</code>. |
+|  [duplicate(num)](./polyethylene.polyasynciterable.duplicate.md) |  | Returns a tuple containing <code>num</code> iterables that will yield independent copies of the elements yielded by <code>this</code>. |
 |  [every(func, options)](./polyethylene.polyasynciterable.every.md) |  | Returns <code>true</code> if calling <code>func(element)</code> returns <code>true</code> for every element, and <code>false</code> otherwise |
 |  [filter(func, options)](./polyethylene.polyasynciterable.filter.md) |  | Return an iteration of the elements of <code>this</code> for which <code>func(element)</code> returns <code>true</code>. |
 |  [filter(func, options)](./polyethylene.polyasynciterable.filter_1.md) |  | Return an iteration of the elements of <code>this</code> for which <code>func(element)</code> returns <code>true</code>. |

docs/polyethylene.polysynciterable._symbol.iterator_.md

@@ -9,11 +9,11 @@ Allows this class to work as a regular `Iterable<T>`
 **Signature:**
 
 ```typescript
-[Symbol.iterator](): Generator<T, void, undefined>;
+[Symbol.iterator](): Iterator<T, void, undefined>;
 ```
 **Returns:**
 
-Generator&lt;T, void, undefined&gt;
+Iterator&lt;T, void, undefined&gt;
 
 an iterable that will yield the same elements as the iterable used to create this instance
 

docs/polyethylene.polysynciterable.duplicate.md

@@ -0,0 +1,34 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [polyethylene](./polyethylene.md) &gt; [PolySyncIterable](./polyethylene.polysynciterable.md) &gt; [duplicate](./polyethylene.polysynciterable.duplicate.md)
+
+## PolySyncIterable.duplicate() method
+
+Returns a tuple containing `num` iterables that will yield independent copies of the elements yielded by `this`<!-- -->.
+
+**Signature:**
+
+```typescript
+duplicate<N extends number>(num: N): Tuple<PolySyncIterable<T>, N>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  num | N | the number of copies to be returned |
+
+**Returns:**
+
+[Tuple](./polyethylene.tuple.md)<!-- -->&lt;[PolySyncIterable](./polyethylene.polysynciterable.md)<!-- -->&lt;T&gt;, N&gt;
+
+An array of `num` elements containing independent copies of this iterable
+
+## Remarks
+
+Note that, as with every other method of this class, this instance is unusable after calling this method.
+
+In order to provide a truly independent iteration for all returned iterables, a buffer is kept, which can grow as big as the whole iteration in certain circumstances. The buffer is filled as fast as the fastest iterable requests new items, and emptied as fast as the slowest iterable requests new items.
+
+Note that for synchronous iterations, it's common to end up with a full buffer if the returned duplicated elements are used in sequence. In this situation, it might be more useful to simply convert the iteration to an array and pass it around, rather than pay the overhead of this method.
+

docs/polyethylene.polysynciterable.md

@@ -34,6 +34,7 @@ The constructor for this class is marked as internal. Third-party code should no
 |  [drop(num)](./polyethylene.polysynciterable.drop.md) |  | Return a new iteration that skips the first <code>num</code> elements. If there were less than <code>num</code> elements in the iteration, no elements are yielded. |
 |  [dropLast(num)](./polyethylene.polysynciterable.droplast.md) |  | Return a new iteration that skips the last <code>num</code> elements. If there were less than <code>num</code> elements in the iteration, no elements are yielded. |
 |  [dropWhile(func)](./polyethylene.polysynciterable.dropwhile.md) |  | Return a new iteration that skips the first few elements for which <code>func(element)</code> returns <code>true</code>. |
+|  [duplicate(num)](./polyethylene.polysynciterable.duplicate.md) |  | Returns a tuple containing <code>num</code> iterables that will yield independent copies of the elements yielded by <code>this</code>. |
 |  [every(func)](./polyethylene.polysynciterable.every.md) |  | Returns <code>true</code> if calling <code>func(element)</code> returns <code>true</code> for every element, and <code>false</code> otherwise |
 |  [filter(func)](./polyethylene.polysynciterable.filter.md) |  | Return an iteration of the elements of <code>this</code> for which <code>func(element)</code> returns <code>true</code>. |
 |  [filter(func)](./polyethylene.polysynciterable.filter_1.md) |  | Return an iteration of the elements of <code>this</code> for which <code>func(element)</code> returns <code>true</code>. |

docs/polyethylene.tuple.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [polyethylene](./polyethylene.md) &gt; [Tuple](./polyethylene.tuple.md)
+
+## Tuple type
+
+A tuple of `N` elements of type `T`<!-- -->.
+
+**Signature:**
+
+```typescript
+export type Tuple<T, N extends number> = [T, ...T[]] & {
+    length: N;
+};
+```

etc/polyethylene.api.json

@@ -1,7 +1,7 @@
 {
   "metadata": {
     "toolPackage": "@microsoft/api-extractor",
-    "toolVersion": "7.34.4",
+    "toolVersion": "7.38.2",
     "schemaVersion": 1011,
     "oldestForwardsCompatibleVersion": 1001,
     "tsdocConfig": {
@@ -3242,6 +3242,89 @@
               "isAbstract": false,
               "name": "dropWhile"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "polyethylene!PolyAsyncIterable#duplicate:member(1)",
+              "docComment": "/**\n * Returns a tuple containing `num` iterables that will yield independent copies of the elements yielded by `this`.\n *\n * @remarks\n *\n * Note that, as with every other method of this class, this instance is unusable after calling this method.\n *\n * In order to provide a truly independent iteration for all returned iterables, a buffer is kept, which can grow as big as the whole iteration in certain circumstances. The buffer is filled as fast as the fastest iterable requests new items, and emptied as fast as the slowest iterable consumes those items.\n *\n * @param num - the number of copies to be returned\n *\n * @returns An array of `num` elements containing independent copies of this iterable\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "duplicate<N extends "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">(num: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "N"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Tuple",
+                  "canonicalReference": "polyethylene!Tuple:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "PolyAsyncIterable",
+                  "canonicalReference": "polyethylene!PolyAsyncIterable:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<T>, N>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "typeParameters": [
+                {
+                  "typeParameterName": "N",
+                  "constraintTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "defaultTypeTokenRange": {
+                    "startIndex": 0,
+                    "endIndex": 0
+                  }
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 9
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "num",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "duplicate"
+            },
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolyAsyncIterable#every:member(1)",
@@ -6384,8 +6467,8 @@
                 },
                 {
                   "kind": "Reference",
-                  "text": "Generator",
-                  "canonicalReference": "!Generator:interface"
+                  "text": "Iterator",
+                  "canonicalReference": "!Iterator:interface"
                 },
                 {
                   "kind": "Content",
@@ -6942,6 +7025,89 @@
               "isAbstract": false,
               "name": "dropWhile"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "polyethylene!PolySyncIterable#duplicate:member(1)",
+              "docComment": "/**\n * Returns a tuple containing `num` iterables that will yield independent copies of the elements yielded by `this`.\n *\n * @remarks\n *\n * Note that, as with every other method of this class, this instance is unusable after calling this method.\n *\n * In order to provide a truly independent iteration for all returned iterables, a buffer is kept, which can grow as big as the whole iteration in certain circumstances. The buffer is filled as fast as the fastest iterable requests new items, and emptied as fast as the slowest iterable requests new items.\n *\n * Note that for synchronous iterations, it's common to end up with a full buffer if the returned duplicated elements are used in sequence. In this situation, it might be more useful to simply convert the iteration to an array and pass it around, rather than pay the overhead of this method.\n *\n * @param num - the number of copies to be returned\n *\n * @returns An array of `num` elements containing independent copies of this iterable\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "duplicate<N extends "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ">(num: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "N"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Tuple",
+                  "canonicalReference": "polyethylene!Tuple:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "PolySyncIterable",
+                  "canonicalReference": "polyethylene!PolySyncIterable:class"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<T>, N>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "typeParameters": [
+                {
+                  "typeParameterName": "N",
+                  "constraintTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "defaultTypeTokenRange": {
+                    "startIndex": 0,
+                    "endIndex": 0
+                  }
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 9
+              },
+              "releaseTag": "Public",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "num",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "duplicate"
+            },
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolySyncIterable#every:member(1)",
@@ -9596,6 +9762,64 @@
               "endIndex": 3
             }
           ]
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "polyethylene!Tuple:type",
+          "docComment": "/**\n * A tuple of `N` elements of type `T`.\n *\n * @typeParam T - The type of elements of the tuple\n *\n * @typeParam N - The number of elements in this tuple\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type Tuple<T, N extends "
+            },
+            {
+              "kind": "Content",
+              "text": "number"
+            },
+            {
+              "kind": "Content",
+              "text": "> = "
+            },
+            {
+              "kind": "Content",
+              "text": "[T, ...T[]] & {\n    length: N;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/lib/types.ts",
+          "releaseTag": "Public",
+          "name": "Tuple",
+          "typeParameters": [
+            {
+              "typeParameterName": "T",
+              "constraintTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            },
+            {
+              "typeParameterName": "N",
+              "constraintTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "typeTokenRange": {
+            "startIndex": 3,
+            "endIndex": 4
+          }
         }
       ]
     }