refactor: improve performance of sync iterables

Darkhogg · Dec 31, 2023 · 2066ecd · 2066ecd
1 parent 2bb2526
commit 2066ecd
Show file tree

Hide file tree

Showing 21 changed files with 528 additions and 436 deletions.
diff --git a/.npmignore b/.npmignore
@@ -76,4 +76,5 @@ etc/
 .github/
 
 # Tests
-dist/tests/
+dist/mjs/tests/
+dist/cjs/tests/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,8 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed:
   - Improved types of `toObject` and `toMap` methods
-  - Add an `options` argument to `PolyAsyncIterable#complete`
-  - Add an `options` argument to `PolyAsyncIterable#join`
+  - Added an `options` argument to `PolyAsyncIterable#complete`
+  - Added an `options` argument to `PolyAsyncIterable#join`
+  - Improved performance of `PolySyncIterable#map` and `PolySyncIterable#filter`
 
 
 ## [2.3.0] - 2023-03-16

diff --git a/docs/polyethylene.baseimpls.md b/docs/polyethylene.baseimpls.md
@@ -0,0 +1,11 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [polyethylene](./polyethylene.md) &gt; [baseImpls](./polyethylene.baseimpls.md)
+
+## baseImpls variable
+
+**Signature:**
+
+```typescript
+baseImpls: BaseImpls
+```
diff --git a/docs/polyethylene.md b/docs/polyethylene.md
@@ -16,6 +16,11 @@ The entry point for this library is the [Poly](./polyethylene.poly.md) namespace
 |  --- | --- |
 |  [AsyncIterableBuilder](./polyethylene.asynciterablebuilder.md) | <p>A class that helps with building an [AsyncIterable](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator) from a non-structured source.</p><p>In order to create the iteration, you must call the [value](./polyethylene.asynciterablebuilder.value.md)<!-- -->, [error](./polyethylene.asynciterablebuilder.error.md) and [done](./polyethylene.asynciterablebuilder.done.md) methods with appropriate arguments.</p> |
 |  [PolyAsyncIterable](./polyethylene.polyasynciterable.md) | <p>An <code>AsyncIterable&lt;T&gt;</code> with a suite of methods for transforming the iteration into other iterations or to get a single result from it.</p><p>This class works as an async version of [PolySyncIterable](./polyethylene.polysynciterable.md)<!-- -->, but all methods accept async function where possible and will always return either <code>PolyAsyncIterables</code> or a <code>Promise</code> to a value.</p><p>\#\# Concurrency Many operations of this class accept as a final argument an [options object](./polyethylene.concurrencyoptions.md) than can specify some options for concurrent operations.</p><p>- The <code>concurrency</code> option will specify how many times whatever <code>func</code> you pass is called before waiting for its results. Effectively, this is the number of promises that can be pending at the same time. If not specified, it will default to 0, meaning no concurrency. Must be a non-negative integer. - The <code>bufferSize</code> option will specify the size of the internal buffer used to store the pending and completed promises. Effectively, this is how many results will be prefetched. If not specified, it will default to <code>concurrency</code>, meaning no extra intermediate results are stored. Must be a positive integer greater or equal to <code>concurrency</code>.</p><p>A concurrency value of 0 acts the same as a 1 concurrency-wise, but disables the concurrency completely, preventing any values to be requested before actually needed.</p><p>Specifying concurrency greater or equal to 1 will make more elements be requested of the previous iterator than actually requested of the current one, similarly to [PolyAsyncIterable.prefetch()](./polyethylene.polyasynciterable.prefetch.md)<!-- -->.</p> |
+
+## Abstract Classes
+
+|  Abstract Class | Description |
+|  --- | --- |
 |  [PolySyncIterable](./polyethylene.polysynciterable.md) | <p>A <code>SyncIterable&lt;T&gt;</code> with a suite of methods for transforming the iteration into other iterations or to get a single result from it.</p><p>The methods of this class are intended to resemble those of <code>Array</code>, with added utilities where appropriate and made for any kind of iterable.</p> |
 
 ## Interfaces
@@ -30,6 +35,12 @@ The entry point for this library is the [Poly](./polyethylene.poly.md) namespace
 |  --- | --- |
 |  [Poly](./polyethylene.poly.md) | Main namespace for the creation of [PolySyncIterable](./polyethylene.polysynciterable.md) and [PolyAsyncIterable](./polyethylene.polyasynciterable.md) objects. |
 
+## Variables
+
+|  Variable | Description |
+|  --- | --- |
+|  [baseImpls](./polyethylene.baseimpls.md) |  |
+
 ## Type Aliases
 
 |  Type Alias | Description |

diff --git a/docs/polyethylene.polysynciterable._symbol.iterator_.md b/docs/polyethylene.polysynciterable._symbol.iterator_.md
@@ -9,11 +9,11 @@ Allows this class to work as a regular `Iterable<T>`
 **Signature:**
 
 ```typescript
-[Symbol.iterator](): Iterator<T, void, undefined>;
+abstract [Symbol.iterator](): Iterator<T>;
 ```
 **Returns:**
 
-Iterator&lt;T, void, undefined&gt;
+Iterator&lt;T&gt;
 
 an iterable that will yield the same elements as the iterable used to create this instance
 
diff --git a/docs/polyethylene.polysynciterable.indexof.md b/docs/polyethylene.polysynciterable.indexof.md
diff --git a/docs/polyethylene.polysynciterable.lastindexof.md b/docs/polyethylene.polysynciterable.lastindexof.md
diff --git a/docs/polyethylene.polysynciterable.md b/docs/polyethylene.polysynciterable.md
@@ -11,19 +11,15 @@ The methods of this class are intended to resemble those of `Array`<!-- -->, wit
 **Signature:**
 
 ```typescript
-export default class PolySyncIterable<T> implements Iterable<T> 
+export default abstract class PolySyncIterable<T> implements Iterable<T> 
 ```
 **Implements:** Iterable&lt;T&gt;
 
-## Remarks
-
-The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `PolySyncIterable` class.
-
 ## Methods
 
 |  Method | Modifiers | Description |
 |  --- | --- | --- |
-|  [\[Symbol.iterator\]()](./polyethylene.polysynciterable._symbol.iterator_.md) |  | Allows this class to work as a regular <code>Iterable&lt;T&gt;</code> |
+|  [\[Symbol.iterator\]()](./polyethylene.polysynciterable._symbol.iterator_.md) | <code>abstract</code> | Allows this class to work as a regular <code>Iterable&lt;T&gt;</code> |
 |  [append(other)](./polyethylene.polysynciterable.append.md) |  | Return a new iteration that will iterate over <code>this</code>, then over <code>other</code>. |
 |  [async()](./polyethylene.polysynciterable.async.md) |  | Return an async version of this same iteration. |
 |  [chunk(num)](./polyethylene.polysynciterable.chunk.md) |  | Return an iteration of arrays of size <code>num</code> (except possibly the last) containing groupings of elements of <code>this</code> iteration. |
@@ -51,9 +47,7 @@ The constructor for this class is marked as internal. Third-party code should no
 |  [forEach(func)](./polyethylene.polysynciterable.foreach.md) |  | Call a function for each element of <code>this</code> iteration. |
 |  [groupBy(func)](./polyethylene.polysynciterable.groupby.md) |  | Return an iteration of group pairs, where the first element is a \_group key\_ and the second is an iterable of all the elements for which <code>func(element)</code> returned the key. |
 |  [includes(obj)](./polyethylene.polysynciterable.includes.md) |  | Returns whether an element is present in this iteration. |
-|  [indexOf(func)](./polyethylene.polysynciterable.indexof.md) |  |  |
 |  [join(glue)](./polyethylene.polysynciterable.join.md) |  | Return the result of joining the elements of <code>this</code> with the given <code>glue</code>, or <code>','</code> if no glue is given. |
-|  [lastIndexOf(func)](./polyethylene.polysynciterable.lastindexof.md) |  |  |
 |  [map(func)](./polyethylene.polysynciterable.map.md) |  | Return an iteration of the result of calling <code>func(element)</code> for every element in <code>this</code>. |
 |  [mapKeys(this, func)](./polyethylene.polysynciterable.mapkeys.md) |  | Return an iteration of the pairs resulting of calling <code>func(element)</code> for every element in <code>this</code> and using it as the first element of the pair (the \*key\*) and preserving the second (the \*value\*). |
 |  [mapValues(this, func)](./polyethylene.polysynciterable.mapvalues.md) |  | Return an iteration of the pairs resulting of calling <code>func(element)</code> for every element in <code>this</code> and using it as the second element of the pair (the \*value\*) and preserving the first (the \*key\*). |

diff --git a/etc/polyethylene.api.json b/etc/polyethylene.api.json
@@ -1,7 +1,7 @@
 {
   "metadata": {
     "toolPackage": "@microsoft/api-extractor",
-    "toolVersion": "7.38.2",
+    "toolVersion": "7.39.0",
     "schemaVersion": 1011,
     "oldestForwardsCompatibleVersion": 1001,
     "tsdocConfig": {
@@ -693,6 +693,30 @@
             }
           ]
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "polyethylene!baseImpls:var",
+          "docComment": "",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "baseImpls: "
+            },
+            {
+              "kind": "Reference",
+              "text": "BaseImpls",
+              "canonicalReference": "polyethylene!~BaseImpls:interface"
+            }
+          ],
+          "fileUrlPath": "src/lib/sync/poly-sync-iterable.ts",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "baseImpls",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "polyethylene!ChunkingPredicate:type",
@@ -6408,11 +6432,11 @@
         {
           "kind": "Class",
           "canonicalReference": "polyethylene!PolySyncIterable:class",
-          "docComment": "/**\n * A `SyncIterable<T>` with a suite of methods for transforming the iteration into other iterations or to get a single result from it.\n *\n * The methods of this class are intended to resemble those of `Array`, with added utilities where appropriate and made for any kind of iterable.\n *\n * @remarks\n *\n * The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `PolySyncIterable` class.\n *\n * @public\n */\n",
+          "docComment": "/**\n * A `SyncIterable<T>` with a suite of methods for transforming the iteration into other iterations or to get a single result from it.\n *\n * The methods of this class are intended to resemble those of `Array`, with added utilities where appropriate and made for any kind of iterable.\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
-              "text": "export default class PolySyncIterable<T> implements "
+              "text": "export default abstract class PolySyncIterable<T> implements "
             },
             {
               "kind": "Reference",
@@ -6428,7 +6452,7 @@
               "text": " "
             }
           ],
-          "fileUrlPath": "src/lib/sync/poly-iterable.ts",
+          "fileUrlPath": "src/lib/sync/poly-sync-iterable.ts",
           "releaseTag": "Public",
           "typeParameters": [
             {
@@ -6443,7 +6467,7 @@
               }
             }
           ],
-          "isAbstract": false,
+          "isAbstract": true,
           "name": "PolySyncIterable",
           "preserveMemberOrder": false,
           "members": [
@@ -6454,7 +6478,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "["
+                  "text": "abstract ["
                 },
                 {
                   "kind": "Reference",
@@ -6472,7 +6496,7 @@
                 },
                 {
                   "kind": "Content",
-                  "text": "<T, void, undefined>"
+                  "text": "<T>"
                 },
                 {
                   "kind": "Content",
@@ -6489,7 +6513,7 @@
               "overloadIndex": 1,
               "parameters": [],
               "isOptional": false,
-              "isAbstract": false,
+              "isAbstract": true,
               "name": "[Symbol.iterator]"
             },
             {
@@ -8124,59 +8148,6 @@
               "isAbstract": false,
               "name": "includes"
             },
-            {
-              "kind": "Method",
-              "canonicalReference": "polyethylene!PolySyncIterable#indexOf:member(1)",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "indexOf(func: "
-                },
-                {
-                  "kind": "Reference",
-                  "text": "IndexedPredicate",
-                  "canonicalReference": "polyethylene!IndexedPredicate:type"
-                },
-                {
-                  "kind": "Content",
-                  "text": "<T>"
-                },
-                {
-                  "kind": "Content",
-                  "text": "): "
-                },
-                {
-                  "kind": "Content",
-                  "text": "number"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isStatic": false,
-              "returnTypeTokenRange": {
-                "startIndex": 4,
-                "endIndex": 5
-              },
-              "releaseTag": "Public",
-              "isProtected": false,
-              "overloadIndex": 1,
-              "parameters": [
-                {
-                  "parameterName": "func",
-                  "parameterTypeTokenRange": {
-                    "startIndex": 1,
-                    "endIndex": 3
-                  },
-                  "isOptional": false
-                }
-              ],
-              "isOptional": false,
-              "isAbstract": false,
-              "name": "indexOf"
-            },
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolySyncIterable#join:member(1)",
@@ -8225,59 +8196,6 @@
               "isAbstract": false,
               "name": "join"
             },
-            {
-              "kind": "Method",
-              "canonicalReference": "polyethylene!PolySyncIterable#lastIndexOf:member(1)",
-              "docComment": "",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "lastIndexOf(func: "
-                },
-                {
-                  "kind": "Reference",
-                  "text": "IndexedPredicate",
-                  "canonicalReference": "polyethylene!IndexedPredicate:type"
-                },
-                {
-                  "kind": "Content",
-                  "text": "<T>"
-                },
-                {
-                  "kind": "Content",
-                  "text": "): "
-                },
-                {
-                  "kind": "Content",
-                  "text": "number"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isStatic": false,
-              "returnTypeTokenRange": {
-                "startIndex": 4,
-                "endIndex": 5
-              },
-              "releaseTag": "Public",
-              "isProtected": false,
-              "overloadIndex": 1,
-              "parameters": [
-                {
-                  "parameterName": "func",
-                  "parameterTypeTokenRange": {
-                    "startIndex": 1,
-                    "endIndex": 3
-                  },
-                  "isOptional": false
-                }
-              ],
-              "isOptional": false,
-              "isAbstract": false,
-              "name": "lastIndexOf"
-            },
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolySyncIterable#map:member(1)",