Added inline docs for utilities.

src/utils/batch.d.ts

@@ -2,6 +2,15 @@ import {none} from '../defs';
 
 export = batch;
 
-type BatchOutput<T> = (value: T) => (T[] | typeof none);
+/**
+ * Batch values into arrays of `n` elements.
+ */
+type BatchOutput<T> = (value: T | typeof none) => (T[] | typeof none);
 
+/**
+ * Creates a function that batches values into arrays of `n` elements.
+ * @param n number of elements in a batch
+ * @returns a flushable function that batches values
+ * @remarks The returned function is a {@link BatchOutput}. It collects values into batches (arrays) of `n` elements. The last batch can have less than `n` elements.
+ */
 declare function batch<T = any>(n?: number): BatchOutput<T>;

src/utils/fixUtf8Stream.d.ts

@@ -1,7 +1,16 @@
 /// <reference types="node" />
 
+import {none} from '../defs';
+
 export = fixUtf8Stream;
 
-type FixOutput = (chunk: string | Buffer) => string;
+/**
+ * Converts buffers to UTF-8 strings and outputs them on the correct character boundaries.
+ */
+type FixOutput = (chunk: string | Buffer | typeof none) => string;
 
+/**
+ * Creates a function that converts buffers to UTF-8 strings and outputs them on the correct character boundaries.
+ * @returns a converter function
+ */
 declare function fixUtf8Stream(): FixOutput;

src/utils/fold.d.ts

@@ -2,11 +2,18 @@ import {none} from '../defs';
 
 export = fold;
 
+/**
+ * Folds values into an accumulator. Returns the accumulator when the source is exhausted.
+ * @param fn function that takes an accumulator and a value and returns an accumulator
+ * @param acc initial accumulator
+ * @returns a function that takes a value and returns an accumulator or {@link none}.
+ * @remarks It is modelled on the [reduce](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) method.
+ */
 declare function fold<A, T>(
   fn: (acc: A, value: T) => A,
   acc: A
-): (value: T) => A | typeof none;
+): (value: T | typeof none) => A | typeof none;
 declare function fold<A, T>(
   fn: (acc: A, value: T) => Promise<A>,
   acc: A
-): (value: T) => Promise<A | typeof none>;
+): (value: T | typeof none) => Promise<A | typeof none>;

src/utils/lines.d.ts

@@ -2,6 +2,13 @@ import {none} from '../defs';
 
 export = lines;
 
-type LinesOutput = (value: string | none) => Generator<string, void, unknown>;
+/**
+ * The flushable function that outputs text in lines.
+ */
+type LinesOutput = (value: string | typeof none) => Generator<string, void, unknown>;
 
+/**
+ * Creates a flushable function that outputs text in lines.
+ * @returns a splitter function
+ */
 declare function lines(): LinesOutput;

src/utils/readableFrom.d.ts

@@ -5,10 +5,22 @@ import {TypedReadable} from '../typed-streams';
 
 export = readableFrom;
 
+/**
+ * A function or an iterable that will be used as a data source.
+ */
 type Iter<T> = (() => T) | (() => Promise<T>) | Iterable<T> | AsyncIterable<T>;
 
+/**
+ * Options for the `readableFrom` function based on `ReadableOptions` with some additional properties.
+ */
 interface ReadableFromOptions<T> extends ReadableOptions {
+  /** An iterable or a function that will be used as a data source. */
   iterable?: Iter<T>;
 }
 
+/**
+ * Creates a readable stream from an iterable or a function that will be used as a data source.
+ * @param options readable options (see {@link ReadableFromOptions}) or an iterable or a function that will be used as a data source.
+ * @returns a readable stream
+ */
 declare function readableFrom<T>(options: Iter<T> | ReadableFromOptions<T>): TypedReadable<T>;

src/utils/reduceStream.d.ts

@@ -5,21 +5,44 @@ import {TypedWritable} from '../typed-streams';
 
 export = reduceStream;
 
+/** A reducer function prototype */
 type Reducer<A, T> = (this: ReduceStreamOutput<A, T>, acc: A, value: T) => A;
+/** An asynchronous reducer function prototype */
 type ReducerPromise<A, T> = (this: ReduceStreamOutput<A, T>, acc: A, value: T) => Promise<A>;
 
+/**
+ * Options for the `reduceStream` function based on `WritableOptions` with some additional properties.
+ */
 interface ReduceStreamOptions<A, T> extends WritableOptions {
+  /** A reducer function. */
   reducer?: Reducer<A, T> | ReducerPromise<A, T>;
+  /** An initial accumulator. */
   initial?: A;
 }
 
+/**
+ * A writable stream that contains an accumulator as a property.
+ */
 interface ReduceStreamOutput<A, T> extends TypedWritable<T> {
   accumulator: A;
 }
 
+/**
+ * Creates a writable stream that contains an accumulator as a property.
+ * @param options options for the reduceStream (see {@link ReduceStreamOptions})
+ * @returns a writable stream
+ * @remarks It is modelled on the [reduce](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) method.
+ */
 declare function reduceStream<A, T>(
   options: ReduceStreamOptions<A, T>
 ): ReduceStreamOutput<A, T>;
+/**
+ * Creates a writable stream that contains an accumulator as a property.
+ * @param reducer a reducer function
+ * @param initial an initial accumulator
+ * @returns a writable stream
+ * @remarks It is modelled on the [reduce](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) method.
+ */
 declare function reduceStream<A, T>(
   reducer: Reducer<A, T> | ReducerPromise<A, T>,
   initial: A

src/utils/scan.d.ts

@@ -1,5 +1,12 @@
 export = scan;
 
+/**
+ * Creates a function that scans values into an accumulator.
+ * @param fn a function that takes an accumulator and a value and returns an accumulator
+ * @param acc an initial accumulator
+ * @returns a function that takes a value and returns an accumulator
+ * @remarks It is a companion for `fold()`. Unlike `fold()` it returns the current accumulator for each value.
+ */
 declare function scan<A, T>(fn: (acc: A, value: T) => A, acc: A): (value: T) => A;
 declare function scan<A, T>(
   fn: (acc: A, value: T) => Promise<A>,

src/utils/skip.d.ts

@@ -2,4 +2,9 @@ import {none} from '../defs';
 
 export = skip;
 
+/**
+ * Creates a function that skips `n` elements.
+ * @param n number of elements to skip
+ * @returns a function that takes a value and returns a value or {@link none} when skipping
+ */
 declare function skip<T = any>(n: number): (value: T) => T | typeof none;

src/utils/skipWhile.d.ts

@@ -2,6 +2,11 @@ import {none} from '../defs';
 
 export = skipWhile;
 
+/**
+ * Creates a function that skips values while `fn` returns `true`.
+ * @param fn a function that takes a value and returns a boolean
+ * @returns a function that takes a value and returns a value or {@link none} when skipping
+ */
 declare function skipWhile<T>(fn: (value: T) => boolean): (value: T) => T | typeof none;
 declare function skipWhile<T>(
   fn: (value: T) => Promise<boolean>

src/utils/take.d.ts

@@ -2,6 +2,12 @@ import {none, stop} from '../defs';
 
 export = take;
 
+/**
+ * Creates a function that takes `n` elements.
+ * @param n number of elements
+ * @param finalValue a value that is returned when `n` elements are taken. It can be {@link none} or {@link stop}. It defaults to {@link none}.
+ * @returns a function that takes a value and returns a value or {@link finalValue} when `n` elements are taken
+ */
 declare function take<T = any>(
   n: number,
   finalValue?: typeof none | typeof stop = none

src/utils/takeWhile.d.ts

@@ -2,6 +2,12 @@ import {none, stop} from './defs';
 
 export = takeWhile;
 
+/**
+ * Creates a function that takes values while `fn` returns `true`.
+ * @param fn a function that takes a value and returns a boolean
+ * @param finalValue a value that is returned when `fn` returns `false`. It can be {@link none} or {@link stop}. It defaults to {@link none}.
+ * @returns a function that takes a value and returns a value or {@link finalValue} when {@link fn} returns `false`
+ */
 declare function takeWhile<T>(
   fn: (value: T) => boolean,
   finalValue?: typeof none | typeof stop = none

src/utils/takeWithSkip.d.ts

@@ -2,6 +2,14 @@ import {none, stop} from '../defs';
 
 export = takeWithSkip;
 
+/**
+ * Creates a function that takes `n` elements after skipping `skip` elements.
+ * @param n number of elements to take
+ * @param skip number of elements to skip (defaults to 0)
+ * @param finalValue a value that is returned when `n` elements are taken. It can be {@link none} or {@link stop}. It defaults to {@link none}.
+ * @returns a function that takes a value and returns a value or {@link finalValue} when `n` elements are taken. It returns {@link none} when `skip` elements are skipped.
+ * @remarks This function is more efficient than `skip()` followed by `take()`.
+ */
 declare function takeWithSkip<T = any>(
   n: number,
   skip?: number,