fix: documentation and code fixes

package.json

@@ -24,6 +24,8 @@
     "prebuild": "rimraf dist build",
     "build": "tsc --module commonjs && rollup -c rollup.config.ts",
     "build-docs": "typedoc",
+    "build-docs:watch": "typedoc --watch",
+    "serve:docs": "serve -l 5000 docs",
     "start": "rollup -c rollup.config.ts -w",
     "test": "jest --coverage",
     "test:watch": "jest --coverage --watch",
@@ -107,6 +109,7 @@
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-typescript2": "^0.30.0",
     "semantic-release": "^17.3.9",
+    "serve": "^11.3.2",
     "shelljs": "^0.8.4",
     "ts-equality-comparer": "^1.0.3",
     "ts-hashmap": "^2.0.3",

src/helpers/toIterable.ts

@@ -1,8 +1,8 @@
 export function toIterable<T, TF extends () => IterableIterator<T>>(f: TF) {
   return {
     [Symbol.iterator]: f,
-    toJSON:function () {
+    toJSON(): T[] {
       return [...f()]
-    }
+    },
   }
 }

src/transformers/all.ts

@@ -1,4 +1,18 @@
 import { every, _every } from './every'
 
+/**
+ * returns `true` if *all* elements in `src` return `true` when passed to `pred`
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _every}
+ * @alias of {@link every}
+ * @param src source sequence
+ * @param pred indexed predicate function
+ */
 export const all = every
+/**
+ * returns `true` if *all* elements in `src` return `true` when passed to `pred`
+ * @alias of {@link _every}
+ * @param src source sequence
+ * @param pred indexed predicate function
+ */
 export const _all = _every

src/transformers/append.ts

@@ -1,13 +1,25 @@
 import { deferP0 } from 'ts-functional-pipe'
 import { toIterable } from '../helpers/toIterable'
 
+/**
+ * append a single item to the end of a sequence
+ * @param src source sequence
+ * @param item the item to append
+ */
 export function _append<T>(src: Iterable<T>, item: T): Iterable<T> {
-  return toIterable(function*() {
+  return toIterable(function* () {
     for (const x of src) {
       yield x
     }
     yield item
   })
 }
 
+/**
+ * append a single item to the end of a sequence
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _append}
+ * @param src source sequence
+ * @param item the item to append
+ */
 export const append = deferP0(_append)

src/transformers/average.ts

@@ -1,12 +1,16 @@
 import { _aggregate } from './aggregate'
 import { deferP0 } from 'ts-functional-pipe'
 
+/**
+ * calculates the average value of a sequence of **`number`**
+ * @param src a sequence of numbers
+ */
 export function _average(src: Iterable<number>): number {
   const f = _aggregate(
     src,
     {
       tot: 0,
-      count: 0
+      count: 0,
     },
     (acc, val) => {
       acc.tot += val
@@ -20,4 +24,11 @@ export function _average(src: Iterable<number>): number {
   return f.tot / f.count
 }
 
+/**
+ * calculates the average value of a sequence of **`number`**
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _average}
+ * @param src a sequence of numbers
+ */
+
 export const average = deferP0(_average)

src/transformers/concat.ts

@@ -1,8 +1,14 @@
 import { toIterable } from '../helpers/toIterable'
 import { deferP0 } from 'ts-functional-pipe'
 
+/**
+ * concatenate any number of sequences to the end of a sequence
+ * @param src the source sequence
+ * @param sequences additional sequences whose items will be appended to the output sequence
+ * @example concat(src, seq1, seq2, seq3)
+ */
 export function _concat<T>(src: Iterable<T>, ...sequences: Array<Iterable<T>>): Iterable<T> {
-  return toIterable(function*() {
+  return toIterable(function* () {
     for (const item of src) {
       yield item
     }
@@ -14,4 +20,12 @@ export function _concat<T>(src: Iterable<T>, ...sequences: Array<Iterable<T>>):
   })
 }
 
+/**
+ * concatenate any number of sequences to the end of a sequence
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _concat}
+ * @param src the source sequence
+ * @param args additional sequences whose items will be appended to the output sequence
+ * @example concat(seq1, seq2, seq3)
+ */
 export const concat = deferP0(_concat)

src/transformers/count.ts

@@ -1,7 +1,12 @@
 import { IndexedPredicate } from '../types/IndexedPredicate'
 import { deferP0 } from 'ts-functional-pipe'
 
-export function _count<T>(src: Iterable<T>, pred: IndexedPredicate<T> = x => true): number {
+/**
+ * count the number of items in a sequence (that optionally satisfy a predicate)
+ * @param src source sequence
+ * @param pred optional predicate function to indicate which values should be included in the count
+ */
+export function _count<T>(src: Iterable<T>, pred: IndexedPredicate<T> = () => true): number {
   let c = 0
   let i = 0
   for (const item of src) {
@@ -11,5 +16,11 @@ export function _count<T>(src: Iterable<T>, pred: IndexedPredicate<T> = x => tru
   }
   return c
 }
-
+/**
+ * count the number of items in a sequence (that optionally satisfy a predicate)
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _count}
+ * @param src source sequence
+ * @param pred optional predicate function to indicate which values should be included in the count
+ */
 export const count = deferP0(_count)

src/transformers/every.ts

@@ -2,8 +2,21 @@ import { IndexedPredicate } from '../types/IndexedPredicate'
 import { _some } from './some'
 import { deferP0 } from 'ts-functional-pipe'
 
+/**
+ * returns `true` if *all* elements in `src` return `true` when passed to `pred`
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _every}
+ * @param src source sequence
+ * @param pred indexed predicate function
+ */
 export const every = deferP0(_every)
 
+/**
+ * returns `true` if *all* elements in `src` return `true` when passed to `pred`
+ *
+ * @param src source sequence
+ * @param pred indexed predicate function
+ */
 export function _every<T>(src: Iterable<T>, pred: IndexedPredicate<T>): boolean {
   return !_some(src, (item, i) => !pred(item, i))
 }

src/transformers/filter.ts

@@ -1,16 +1,33 @@
 import { toIterable } from '../helpers/toIterable'
 import { IndexedPredicate } from '../types/IndexedPredicate'
 import { deferP0 } from 'ts-functional-pipe'
+import { _indexed } from './indexed'
 
+/**
+ * creates a new sequence with every item of the source sequence for which the predicate function returns `true`
+ * @param src source sequence
+ * @param pred a function that returns `true` to signal inclusion, `false` to exclude
+ * @returns a new (possibly shorter) sequence with some items filtered away
+ */
 export function _filter<T>(src: Iterable<T>, pred: IndexedPredicate<T>): Iterable<T> {
   return toIterable(function* () {
-    let i = 0
-    for (const x of src) {
-      if (pred(x, i++)) {
-        yield x
+    const s = _indexed(src)
+    for (const x of s) {
+      if (pred(...x)) {
+        yield x[0]
       }
     }
   })
 }
 
+/**
+ * creates a new sequence with every item of the source sequence for which the predicate function returns `true`
+ *
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _filter}
+ *
+ * @param src source sequence
+ * @param pred a function that returns `true` to signal inclusion, `false` to exclude
+ * @returns a new (possibly shorter) sequence with some items filtered away
+ */
 export const filter = deferP0(_filter)

src/transformers/first.ts

@@ -1,11 +1,11 @@
 import { IndexedPredicate } from '../types/IndexedPredicate'
 import { deferP0 } from 'ts-functional-pipe'
+import { _indexed } from './indexed'
 
-export function _first<T>(src: Iterable<T>, pred: IndexedPredicate<T> = x => true): T {
-  let i = 0
-  for (const item of src) {
-    if (pred(item, i++)) {
-      return item
+export function _first<T>(src: Iterable<T>, pred: IndexedPredicate<T> = (x) => true): T {
+  for (const x of _indexed(src)) {
+    if (pred(...x)) {
+      return x[0]
     }
   }
   throw Error('sequence contains no elements')

src/transformers/groupBy.ts

@@ -14,7 +14,9 @@ function createGroupedIterable<K, V>(key: K, value: Iterable<V>): GroupedIterabl
       }
     },
     key,
-    toJSON: () => [...value],
+    toJSON(): V[] {
+      return [...value]
+    },
   }
 }
 

src/transformers/map.ts

@@ -2,6 +2,12 @@ import { IndexedSelector } from '../types/IndexedSelector'
 import { toIterable } from '../helpers/toIterable'
 import { deferP0 } from 'ts-functional-pipe'
 
+/**
+ * Creates a new sequence populated with the results of calling a provided function on every element in the source sequence
+ * @param src source sequence
+ * @param selector function to transform each item `T` in the source sequence into `TOut`
+ * @returns A new sequence with each element being the result of the selector function.
+ */
 export function _map<T, TOut>(
   src: Iterable<T>,
   selector: IndexedSelector<T, TOut>
@@ -14,4 +20,13 @@ export function _map<T, TOut>(
   })
 }
 
+/**
+ * Creates a new sequence populated with the results of calling a provided function on every element in the source sequence
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _map}
+ * @param src source sequence
+ * @param selector function to transform each item `T` in the source sequence into `TOut`
+ * @returns A new sequence with each element being the result of the selector function.
+ */
+
 export const map = deferP0(_map)

src/transformers/select.ts

@@ -1,4 +1,21 @@
 import { map, _map } from './map'
 
+/**
+ * Creates a new sequence populated with the results of calling a provided function on every element in the source sequence
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _map}
+ * @alias of {@link map}
+ * @param src source sequence
+ * @param selector function to transform each item `T` in the source sequence into `TOut`
+ * @returns A new sequence with each element being the result of the selector function.
+ */
+
 export const select = map
+/**
+ * Creates a new sequence populated with the results of calling a provided function on every element in the source sequence
+ * @alias of {@link _map}
+ * @param src source sequence
+ * @param selector function to transform each item `T` in the source sequence into `TOut`
+ * @returns A new sequence with each element being the result of the selector function.
+ */
 export const _select = _map

src/transformers/some.ts

@@ -1,6 +1,12 @@
 import { IndexedPredicate } from '../types/IndexedPredicate'
 import { deferP0 } from 'ts-functional-pipe'
 
+/**
+ * returns `true` if *any* elements in `src` return `true` when passed to `pred`
+ * @remarks does not enumerate further if `pred` returns `false` on a value
+ * @param src source sequence
+ * @param pred indexed predicate function
+ */
 export function _some<T>(src: Iterable<T>, pred: IndexedPredicate<T> = (x) => true): boolean {
   let i = 0
   for (const item of src) {
@@ -10,5 +16,12 @@ export function _some<T>(src: Iterable<T>, pred: IndexedPredicate<T> = (x) => tr
   }
   return false
 }
-
+/**
+ * returns `true` if *any* elements in `src` return `true` when passed to `pred`
+ * @remarks does not enumerate further if `pred` returns `false` on a value
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _every}
+ * @param src source sequence
+ * @param pred indexed predicate function
+ */
 export const some = deferP0(_some)

src/transformers/where.ts

@@ -1,4 +1,23 @@
 import { filter, _filter } from './filter'
 
+/**
+ * creates a new sequence with every item of the source sequence for which the predicate function returns `true`
+ * @remarks
+ * {@link https://biggyspender.github.io/ts-functional-pipe/globals.html#deferp0 P0 deferred} version of {@link _filter}
+ * @alias of {@link filter}
+ *
+ * @param src source sequence
+ * @param pred a function that returns `true` to signal inclusion, `false` to exclude
+ * @returns a new (possibly shorter) sequence with some items filtered away
+ */
+
 export const where = filter
+/**
+ * creates a new sequence with every item of the source sequence for which the predicate function returns `true`
+ *
+ * @alias of {@link _filter}
+ * @param src source sequence
+ * @param pred a function that returns `true` to signal inclusion, `false` to exclude
+ * @returns a new (possibly shorter) sequence with some items filtered away
+ */
 export const _where = _filter

src/types/GroupedIterable.ts

@@ -1,4 +1,4 @@
 export interface GroupedIterable<K, V> extends Iterable<V> {
-  key: K;
-  toJSON(): Array<V>;
+  key: K
+  toJSON(): V[]
 }

src/types/IndexedPredicate.ts

@@ -1 +1,7 @@
+/**
+ * Defines a predicate that takes a value `x:T` and number that represents the position of `x` in whichever sequence
+ * it is applied to and returns `true` or `false` usually to signal inclusion in an output list
+ * @example {@link _filter}
+ */
+
 export type IndexedPredicate<T> = (x: T, i: number) => Boolean

src/types/IndexedSelector.ts

@@ -1 +1,5 @@
+/**
+ * Defines a selector that takes a value `x:T` and number that represents the position of `x` in whichever sequence it is applied to and transforms that `T` into a `TOut`
+ * @example {@link _map}
+ */
 export type IndexedSelector<T, TOut> = (x: T, i: number) => TOut