fix: fix docs and improve existing types

CHANGELOG.md

@@ -6,6 +6,16 @@ This file is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [2.5.1] - 2023-12-31
+
+### Changed:
+  - Fixed documentation for `mapKeys` and `mapValues`
+  - Added `const` to return generic types of `map`, `mapKeys`, `mapValues`, `flatMap` and `reduce`.
+    This should reduce the instances where `as const` is needed before calling method that restrict the `this` type to
+    pairs of elements, such as `toMap` or `toObject`.  This *might* break the types of some existing code if they were
+    relying in generalized inference of literals or arrays.
+
+
 ## [2.5.0] - 2023-12-31
 
 ### Added:
@@ -19,8 +29,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [2.4.0] - 2023-07-04
 
 ### Added:
-  - Added `mapKey` method to both iterables
-  - Added `mapValue` method to both iterables
+  - Added `mapKeys` method to both iterables
+  - Added `mapValues` method to both iterables
 
 ### Changed:
   - Added an `options` argument to `PolyAsyncIterable#complete`

docs/polyethylene.polyasynciterable.flatmap.md

@@ -9,7 +9,7 @@ Return an iteration of elements of the sub-iterables that result from calling `f
 **Signature:**
 
 ```typescript
-flatMap<U>(func: AsyncIndexedMapping<T, Iterable<U> | AsyncIterable<U>>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
+flatMap<const U>(func: AsyncIndexedMapping<T, Iterable<U> | AsyncIterable<U>>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
 ```
 
 ## Parameters

docs/polyethylene.polyasynciterable.map.md

@@ -9,7 +9,7 @@ Return an iteration of the result of calling `func(element)` for every element i
 **Signature:**
 
 ```typescript
-map<U>(func: AsyncIndexedMapping<T, U>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
+map<const U>(func: AsyncIndexedMapping<T, U>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
 ```
 
 ## Parameters

docs/polyethylene.polyasynciterable.mapkeys.md

@@ -9,7 +9,7 @@ Return an iteration of the pairs resulting of calling `func(element)` for every
 **Signature:**
 
 ```typescript
-mapKeys<K1, K2, V>(this: PolyAsyncIterable<[K1, V]>, func: AsyncIndexedMapping<[K1, V], K2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K2, V]>;
+mapKeys<K1, const K2, V>(this: PolyAsyncIterable<[K1, V]>, func: AsyncIndexedMapping<[K1, V], K2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K2, V]>;
 ```
 
 ## Parameters

docs/polyethylene.polyasynciterable.mapvalues.md

@@ -9,7 +9,7 @@ Return an iteration of the pairs resulting of calling `func(element)` for every
 **Signature:**
 
 ```typescript
-mapValues<K, V1, V2>(this: PolyAsyncIterable<[K, V1]>, func: AsyncIndexedMapping<[K, V1], V2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K, V2]>;
+mapValues<K, V1, const V2>(this: PolyAsyncIterable<[K, V1]>, func: AsyncIndexedMapping<[K, V1], V2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K, V2]>;
 ```
 
 ## Parameters

docs/polyethylene.polyasynciterable.reduce_1.md

@@ -9,7 +9,7 @@ Returns the result of calling the passed `reducer` for all elements of the itera
 **Signature:**
 
 ```typescript
-reduce<U>(reducer: AsyncIndexedReducer<T, U>, init: U): Promise<U>;
+reduce<const U>(reducer: AsyncIndexedReducer<T, U>, init: U): Promise<U>;
 ```
 
 ## Parameters

docs/polyethylene.polysynciterable.flatmap.md

@@ -9,7 +9,7 @@ Return an iteration of elements of the sub-iterables that result from calling `f
 **Signature:**
 
 ```typescript
-flatMap<U>(func: IndexedMapping<T, Iterable<U>>): PolySyncIterable<U>;
+flatMap<const U>(func: IndexedMapping<T, Iterable<U>>): PolySyncIterable<U>;
 ```
 
 ## Parameters

docs/polyethylene.polysynciterable.map.md

@@ -9,7 +9,7 @@ Return an iteration of the result of calling `func(element)` for every element i
 **Signature:**
 
 ```typescript
-map<U>(func: IndexedMapping<T, U>): PolySyncIterable<U>;
+map<const U>(func: IndexedMapping<T, U>): PolySyncIterable<U>;
 ```
 
 ## Parameters

docs/polyethylene.polysynciterable.mapkeys.md

@@ -9,7 +9,7 @@ Return an iteration of the pairs resulting of calling `func(element)` for every
 **Signature:**
 
 ```typescript
-mapKeys<K1, K2, V>(this: PolySyncIterable<[K1, V]>, func: IndexedMapping<[K1, V], K2>): PolySyncIterable<[K2, V]>;
+mapKeys<K1, const K2, V>(this: PolySyncIterable<[K1, V]>, func: IndexedMapping<[K1, V], K2>): PolySyncIterable<[K2, V]>;
 ```
 
 ## Parameters
@@ -23,7 +23,7 @@ mapKeys<K1, K2, V>(this: PolySyncIterable<[K1, V]>, func: IndexedMapping<[K1, V]
 
 [PolySyncIterable](./polyethylene.polysynciterable.md)<!-- -->&lt;\[K2, V\]&gt;
 
-A new [PolySyncIterable](./polyethylene.polysynciterable.md) that yields the results of calling `func(element)` for every element of `this` and using it to replace the keys
+A new [PolySyncIterable](./polyethylene.polysynciterable.md) that yields the results of calling `func(element)` for every element of `this` and uses it to replace the keys
 
 ## Remarks
 

docs/polyethylene.polysynciterable.mapvalues.md

@@ -9,7 +9,7 @@ Return an iteration of the pairs resulting of calling `func(element)` for every
 **Signature:**
 
 ```typescript
-mapValues<K, V1, V2>(this: PolySyncIterable<[K, V1]>, func: IndexedMapping<[K, V1], V2>): PolySyncIterable<[K, V2]>;
+mapValues<K, V1, const V2>(this: PolySyncIterable<[K, V1]>, func: IndexedMapping<[K, V1], V2>): PolySyncIterable<[K, V2]>;
 ```
 
 ## Parameters

docs/polyethylene.polysynciterable.reduce_1.md

@@ -9,7 +9,7 @@ Returns the result of calling the passed `reducer` for all elements of the itera
 **Signature:**
 
 ```typescript
-reduce<U>(reducer: IndexedReducer<T, U>, init: U): U;
+reduce<const U>(reducer: IndexedReducer<T, U>, init: U): U;
 ```
 
 ## Parameters

etc/polyethylene.api.json

@@ -4204,7 +4204,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "flatMap<U>(func: "
+                  "text": "flatMap<const U>(func: "
                 },
                 {
                   "kind": "Reference",
@@ -4694,7 +4694,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "map<U>(func: "
+                  "text": "map<const U>(func: "
                 },
                 {
                   "kind": "Reference",
@@ -4778,11 +4778,11 @@
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolyAsyncIterable#mapKeys:member(1)",
-              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the first element of the pair (the *key*) and preserving the second (the *value*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam U - The return type of `func` and the generic type of the resulting iterable\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and using it to replace the keys\n */\n",
+              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the first element of the pair (the *key*) and preserving the second (the *value*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam K1 - The key type of the original iterable, as passed to `func`\n *\n * @typeParam K2 - The key type of the resulting iterable, as returned from `func`\n *\n * @typeParam V - The value type of the original and resulting iterables, as passed to `func`\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and using it to replace the keys\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "mapKeys<K1, K2, V>(this: "
+                  "text": "mapKeys<K1, const K2, V>(this: "
                 },
                 {
                   "kind": "Reference",
@@ -4909,11 +4909,11 @@
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolyAsyncIterable#mapValues:member(1)",
-              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the second element of the pair (the *value*) and preserving the first (the *key*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam U - The return type of `func` and the generic type of the resulting iterable\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and using it to replace the values\n */\n",
+              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the second element of the pair (the *value*) and preserving the first (the *key*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam K - The key type of the original and resulting iterables, as passed to `func`\n *\n * @typeParam V1 - The value type of the original iterable, as passed to `func`\n *\n * @typeParam V2 - The value type of the resulting iterable, as returned from `func`\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and using it to replace the values\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "mapValues<K, V1, V2>(this: "
+                  "text": "mapValues<K, V1, const V2>(this: "
                 },
                 {
                   "kind": "Reference",
@@ -5234,7 +5234,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "reduce<U>(reducer: "
+                  "text": "reduce<const U>(reducer: "
                 },
                 {
                   "kind": "Reference",
@@ -7790,7 +7790,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "flatMap<U>(func: "
+                  "text": "flatMap<const U>(func: "
                 },
                 {
                   "kind": "Reference",
@@ -8179,7 +8179,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "map<U>(func: "
+                  "text": "map<const U>(func: "
                 },
                 {
                   "kind": "Reference",
@@ -8246,11 +8246,11 @@
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolySyncIterable#mapKeys:member(1)",
-              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the first element of the pair (the *key*) and preserving the second (the *value*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam U - The return type of `func` and the generic type of the resulting iterable\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and using it to replace the keys\n */\n",
+              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the first element of the pair (the *key*) and preserving the second (the *value*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam K1 - The key type of the original iterable, as passed to `func`\n *\n * @typeParam K2 - The key type of the resulting iterable, as returned from `func`\n *\n * @typeParam V - The value type of the original and resulting iterables, as passed to `func`\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and uses it to replace the keys\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "mapKeys<K1, K2, V>(this: "
+                  "text": "mapKeys<K1, const K2, V>(this: "
                 },
                 {
                   "kind": "Reference",
@@ -8360,11 +8360,11 @@
             {
               "kind": "Method",
               "canonicalReference": "polyethylene!PolySyncIterable#mapValues:member(1)",
-              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the second element of the pair (the *value*) and preserving the first (the *key*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam U - The return type of `func` and the generic type of the resulting iterable\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and using it to replace the values\n */\n",
+              "docComment": "/**\n * Return an iteration of the pairs resulting of calling `func(element)` for every element in `this` and using it as the second element of the pair (the *value*) and preserving the first (the *key*).\n *\n * @remarks\n *\n * This method is only available for iterations of pairs.\n *\n * @param func - A function that takes an element of `this` and returns something else\n *\n * @typeParam K - The key type of the original and resulting iterables, as passed to `func`\n *\n * @typeParam V1 - The value type of the original iterable, as passed to `func`\n *\n * @typeParam V2 - The value type of the resulting iterable, as returned from `func`\n *\n * @returns A new {@link PolySyncIterable} that yields the results of calling `func(element)` for every element of `this` and using it to replace the values\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "mapValues<K, V1, V2>(this: "
+                  "text": "mapValues<K, V1, const V2>(this: "
                 },
                 {
                   "kind": "Reference",
@@ -8618,7 +8618,7 @@
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "reduce<U>(reducer: "
+                  "text": "reduce<const U>(reducer: "
                 },
                 {
                   "kind": "Reference",

etc/polyethylene.api.md

@@ -111,19 +111,19 @@ export class PolyAsyncIterable<T> implements AsyncIterable<T> {
     findLast(func: AsyncIndexedPredicate<T>, options?: ConcurrencyOptions): Promise<T | undefined>;
     findLastIndex(func: AsyncIndexedPredicate<T>, options?: ConcurrencyOptions): Promise<number>;
     flat<U>(this: PolyAsyncIterable<Iterable<U> | AsyncIterable<U>>): PolyAsyncIterable<U>;
-    flatMap<U>(func: AsyncIndexedMapping<T, Iterable<U> | AsyncIterable<U>>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
+    flatMap<const U>(func: AsyncIndexedMapping<T, Iterable<U> | AsyncIterable<U>>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
     flatten<U>(this: PolyAsyncIterable<Iterable<U> | AsyncIterable<U>>): PolyAsyncIterable<U>;
     forEach(func: AsyncIndexedRunnable<T>, options?: ConcurrencyOptions): Promise<void>;
     groupBy<K>(func: AsyncIndexedMapping<T, K>, options?: ConcurrencyOptions): PolyAsyncIterable<[K, Array<T>]>;
     includes(obj: T): Promise<boolean>;
     join(glue?: string, options?: ConcurrencyOptions): Promise<string>;
-    map<U>(func: AsyncIndexedMapping<T, U>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
-    mapKeys<K1, K2, V>(this: PolyAsyncIterable<[K1, V]>, func: AsyncIndexedMapping<[K1, V], K2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K2, V]>;
-    mapValues<K, V1, V2>(this: PolyAsyncIterable<[K, V1]>, func: AsyncIndexedMapping<[K, V1], V2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K, V2]>;
+    map<const U>(func: AsyncIndexedMapping<T, U>, options?: ConcurrencyOptions): PolyAsyncIterable<U>;
+    mapKeys<K1, const K2, V>(this: PolyAsyncIterable<[K1, V]>, func: AsyncIndexedMapping<[K1, V], K2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K2, V]>;
+    mapValues<K, V1, const V2>(this: PolyAsyncIterable<[K, V1]>, func: AsyncIndexedMapping<[K, V1], V2>, options?: ConcurrencyOptions): PolyAsyncIterable<[K, V2]>;
     prefetch(): PolyAsyncIterable<T>;
     prepend<U>(other: Iterable<U> | AsyncIterable<U>): PolyAsyncIterable<T | U>;
     reduce(reducer: AsyncIndexedReducer<T, T>, init?: T): Promise<T>;
-    reduce<U>(reducer: AsyncIndexedReducer<T, U>, init: U): Promise<U>;
+    reduce<const U>(reducer: AsyncIndexedReducer<T, U>, init: U): Promise<U>;
     reverse(): PolyAsyncIterable<T>;
     slice(start: number, end?: number): PolyAsyncIterable<T>;
     some(func: AsyncIndexedPredicate<T>, options?: ConcurrencyOptions): Promise<boolean>;
@@ -166,18 +166,18 @@ export abstract class PolySyncIterable<T> implements Iterable<T> {
     findLast(func: IndexedPredicate<T>): T | undefined;
     findLastIndex(func: IndexedPredicate<T>): number;
     flat<U>(this: PolySyncIterable<Iterable<U>>): PolySyncIterable<U>;
-    flatMap<U>(func: IndexedMapping<T, Iterable<U>>): PolySyncIterable<U>;
+    flatMap<const U>(func: IndexedMapping<T, Iterable<U>>): PolySyncIterable<U>;
     flatten<U>(this: PolySyncIterable<Iterable<U>>): PolySyncIterable<U>;
     forEach(func: IndexedRunnable<T>): void;
     groupBy<K>(func: IndexedMapping<T, K>): PolySyncIterable<[K, Array<T>]>;
     includes(obj: T): boolean;
     join(glue?: string): string;
-    map<U>(func: IndexedMapping<T, U>): PolySyncIterable<U>;
-    mapKeys<K1, K2, V>(this: PolySyncIterable<[K1, V]>, func: IndexedMapping<[K1, V], K2>): PolySyncIterable<[K2, V]>;
-    mapValues<K, V1, V2>(this: PolySyncIterable<[K, V1]>, func: IndexedMapping<[K, V1], V2>): PolySyncIterable<[K, V2]>;
+    map<const U>(func: IndexedMapping<T, U>): PolySyncIterable<U>;
+    mapKeys<K1, const K2, V>(this: PolySyncIterable<[K1, V]>, func: IndexedMapping<[K1, V], K2>): PolySyncIterable<[K2, V]>;
+    mapValues<K, V1, const V2>(this: PolySyncIterable<[K, V1]>, func: IndexedMapping<[K, V1], V2>): PolySyncIterable<[K, V2]>;
     prepend<U>(other: Iterable<U>): PolySyncIterable<T | U>;
     reduce(reducer: IndexedReducer<T, T>, init?: T): T;
-    reduce<U>(reducer: IndexedReducer<T, U>, init: U): U;
+    reduce<const U>(reducer: IndexedReducer<T, U>, init: U): U;
     reverse(): PolySyncIterable<T>;
     slice(start: number, end?: number): PolySyncIterable<T>;
     some(func: IndexedPredicate<T>): boolean;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "polyethylene",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Functional programming for iterables and async iterables",
   "author": "Daniel Escoz <[email protected]>",
   "license": "MIT",