iterable-linq-utility 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -6,6 +6,22 @@
  */
 export declare type Action<T> = (value: T, index: number) => Unit;
 
+/**
+ * Lazily yields the values of `iterable`, then `value`.
+ * `value` is yielded only when the source ends, so it is never reached on an infinite source.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded after the last value of the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by `value`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.append([1, 2, 3], 4)); // [1, 2, 3, 4]
+ * ```
+ * @since 0.8.0
+ */
+declare function append<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Callback of `forEachAsync`: an async side effect run on each value.
  * @param value - the current value
@@ -103,6 +119,23 @@ declare type ComparerFunction<T> = (a: T, b: T) => number;
 
 declare type ComparingProps<T> = keyof T | Array<keyof T>;
 
+/**
+ * Lazily yields the values of `iterable`, then the values of each iterable in `others`, in order.
+ * Each iterable is opened only when the previous one ends, so the iterables after an infinite one are never read.
+ * Stopping early closes only the iterable being read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param others - the iterables read after the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by the values of `others`
+ * @throws Error if `iterable` or a value of `others` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.concat([1, 2], [3], new Set([4, 5]))); // [1, 2, 3, 4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function concat<T>(iterable: Iterable<T>, ...others: Iterable<T>[]): Iterable<T>;
+
 /**
  * Counts the values of `iterable`; reads the whole source.
  * @operation `Action`
@@ -451,9 +484,11 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 
 declare namespace Functions {
     export {
+        append,
         at,
         average,
         collectToArray,
+        concat,
         count,
         distinct,
         empty_2 as empty,
@@ -476,6 +511,7 @@ declare namespace Functions {
         memoize,
         getMemoizeDefaultOptions,
         min,
+        prepend,
         range,
         reduce,
         repeat_2 as repeat,
@@ -483,6 +519,7 @@ declare namespace Functions {
         single,
         skip,
         skipWhile,
+        slice,
         some,
         sum,
         take,
@@ -528,6 +565,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * Yields the values of the chain, then `value`.
+     * `value` is yielded only when the source ends, so it is never reached on an infinite chain.
+     * @operation `Transformation`
+     * @param value - the value yielded after the last value of the chain
+     * @returns a new chain with the values of this chain followed by `value`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).append(4).collectToArray(); // [1, 2, 3, 4]
+     * ```
+     * @since 0.8.0
+     */
+    append(value: T): IIterableLinq<T>;
     /**
      * Returns the value at `index`, like `Array.prototype.at`; a negative index counts from the end.
      * A non-negative index runs the chain up to the value, then closes the source; a negative index runs the whole chain,
@@ -581,6 +631,21 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     collectToArray(): T[];
+    /**
+     * Yields the values of the chain, then the values of each iterable in `others`, in order.
+     * Each iterable is opened only when the previous one ends, so the iterables after an infinite chain are never read.
+     * Stopping early closes only the iterable being read.
+     * @operation `Transformation`
+     * @param others - the iterables read after the chain; other chains are iterables too
+     * @returns a new chain with the values of this chain followed by the values of `others`
+     * @throws Error if a value of `others` is missing or does not implement `[Symbol.iterator]`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2]).concat([3], new Set([4, 5])).collectToArray(); // [1, 2, 3, 4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    concat(...others: Iterable<T>[]): IIterableLinq<T>;
     /**
      * Counts the values of the chain; runs the whole chain.
      * @operation `Action`
@@ -925,6 +990,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.8
      */
     min(comparer?: Comparer<T>): T | undefined;
+    /**
+     * Yields `value`, then the values of the chain.
+     * `value` is yielded before the source is read.
+     * @operation `Transformation`
+     * @param value - the value yielded before the first value of the chain
+     * @returns a new chain with `value` followed by the values of this chain
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).prepend(0).collectToArray(); // [0, 1, 2, 3]
+     * ```
+     * @since 0.8.0
+     */
+    prepend(value: T): IIterableLinq<T>;
     /**
      * Runs the chain and accumulates its values into a single result, starting from the first value.
      * @operation `Action`
@@ -1040,6 +1118,24 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     skipWhile(predicate: Predicate<T>): IIterableLinq<T>;
+    /**
+     * Yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+     * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite chain.
+     * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+     * A negative `start` runs the whole chain before yielding, keeping only the last `-start` values.
+     * @operation `Transformation`
+     * @param start - an integer, `0` by default; `-1` is the last value
+     * @param end - an integer; the values are yielded up to the end of the chain by default
+     * @returns a new chain with the values from `start` to `end`
+     * @throws Error if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(1, 3).collectToArray(); // [2, 3]
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(-2).collectToArray(); // [4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    slice(start?: number, end?: number): IIterableLinq<T>;
     /**
      * Runs the chain until its first value, then stops and closes the source.
      * @operation `Action`
@@ -1408,6 +1504,22 @@ export declare function override<K extends Extract<keyof IIterableLinq<unknown>,
  */
 export declare type Predicate<T> = (value: T, index: number) => boolean;
 
+/**
+ * Lazily yields `value`, then the values of `iterable`.
+ * `value` is yielded before the source is read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded before the first value of the source
+ * @returns a lazy, re-runnable `Iterable` of `value` followed by the values of the source
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.prepend([1, 2, 3], 0)); // [0, 1, 2, 3]
+ * ```
+ * @since 0.8.0
+ */
+declare function prepend<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Returns the numbers from 0 up to, but not including, `end`, computed as `index * step`.
  * The direction follows the sign of `end`; `reverse` yields the same numbers backwards; a `NaN` bound gives an empty `Iterable`.
@@ -1616,6 +1728,26 @@ declare function skip<T>(iterable: Iterable<T>, count: number): Iterable<T>;
  */
 declare function skipWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
 
+/**
+ * Lazily yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+ * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite source.
+ * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+ * A negative `start` reads the whole source before yielding, keeping only the last `-start` values.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param start - an integer, `0` by default; `-1` is the last value
+ * @param end - an integer; the values are yielded up to the end of the source by default
+ * @returns a lazy, re-runnable `Iterable` of the values from `start` to `end`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], 1, 3)); // [2, 3]
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], -2)); // [4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function slice<T>(iterable: Iterable<T>, start?: number, end?: number): Iterable<T>;
+
 /**
  * Tells whether `iterable` contains a value; reads one value, then closes the source.
  * @operation `Action`

package/dist/index.d.ts

@@ -6,6 +6,22 @@
  */
 export declare type Action<T> = (value: T, index: number) => Unit;
 
+/**
+ * Lazily yields the values of `iterable`, then `value`.
+ * `value` is yielded only when the source ends, so it is never reached on an infinite source.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded after the last value of the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by `value`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.append([1, 2, 3], 4)); // [1, 2, 3, 4]
+ * ```
+ * @since 0.8.0
+ */
+declare function append<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Callback of `forEachAsync`: an async side effect run on each value.
  * @param value - the current value
@@ -103,6 +119,23 @@ declare type ComparerFunction<T> = (a: T, b: T) => number;
 
 declare type ComparingProps<T> = keyof T | Array<keyof T>;
 
+/**
+ * Lazily yields the values of `iterable`, then the values of each iterable in `others`, in order.
+ * Each iterable is opened only when the previous one ends, so the iterables after an infinite one are never read.
+ * Stopping early closes only the iterable being read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param others - the iterables read after the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by the values of `others`
+ * @throws Error if `iterable` or a value of `others` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.concat([1, 2], [3], new Set([4, 5]))); // [1, 2, 3, 4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function concat<T>(iterable: Iterable<T>, ...others: Iterable<T>[]): Iterable<T>;
+
 /**
  * Counts the values of `iterable`; reads the whole source.
  * @operation `Action`
@@ -451,9 +484,11 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 
 declare namespace Functions {
     export {
+        append,
         at,
         average,
         collectToArray,
+        concat,
         count,
         distinct,
         empty_2 as empty,
@@ -476,6 +511,7 @@ declare namespace Functions {
         memoize,
         getMemoizeDefaultOptions,
         min,
+        prepend,
         range,
         reduce,
         repeat_2 as repeat,
@@ -483,6 +519,7 @@ declare namespace Functions {
         single,
         skip,
         skipWhile,
+        slice,
         some,
         sum,
         take,
@@ -528,6 +565,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * Yields the values of the chain, then `value`.
+     * `value` is yielded only when the source ends, so it is never reached on an infinite chain.
+     * @operation `Transformation`
+     * @param value - the value yielded after the last value of the chain
+     * @returns a new chain with the values of this chain followed by `value`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).append(4).collectToArray(); // [1, 2, 3, 4]
+     * ```
+     * @since 0.8.0
+     */
+    append(value: T): IIterableLinq<T>;
     /**
      * Returns the value at `index`, like `Array.prototype.at`; a negative index counts from the end.
      * A non-negative index runs the chain up to the value, then closes the source; a negative index runs the whole chain,
@@ -581,6 +631,21 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     collectToArray(): T[];
+    /**
+     * Yields the values of the chain, then the values of each iterable in `others`, in order.
+     * Each iterable is opened only when the previous one ends, so the iterables after an infinite chain are never read.
+     * Stopping early closes only the iterable being read.
+     * @operation `Transformation`
+     * @param others - the iterables read after the chain; other chains are iterables too
+     * @returns a new chain with the values of this chain followed by the values of `others`
+     * @throws Error if a value of `others` is missing or does not implement `[Symbol.iterator]`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2]).concat([3], new Set([4, 5])).collectToArray(); // [1, 2, 3, 4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    concat(...others: Iterable<T>[]): IIterableLinq<T>;
     /**
      * Counts the values of the chain; runs the whole chain.
      * @operation `Action`
@@ -925,6 +990,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.8
      */
     min(comparer?: Comparer<T>): T | undefined;
+    /**
+     * Yields `value`, then the values of the chain.
+     * `value` is yielded before the source is read.
+     * @operation `Transformation`
+     * @param value - the value yielded before the first value of the chain
+     * @returns a new chain with `value` followed by the values of this chain
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).prepend(0).collectToArray(); // [0, 1, 2, 3]
+     * ```
+     * @since 0.8.0
+     */
+    prepend(value: T): IIterableLinq<T>;
     /**
      * Runs the chain and accumulates its values into a single result, starting from the first value.
      * @operation `Action`
@@ -1040,6 +1118,24 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     skipWhile(predicate: Predicate<T>): IIterableLinq<T>;
+    /**
+     * Yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+     * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite chain.
+     * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+     * A negative `start` runs the whole chain before yielding, keeping only the last `-start` values.
+     * @operation `Transformation`
+     * @param start - an integer, `0` by default; `-1` is the last value
+     * @param end - an integer; the values are yielded up to the end of the chain by default
+     * @returns a new chain with the values from `start` to `end`
+     * @throws Error if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(1, 3).collectToArray(); // [2, 3]
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(-2).collectToArray(); // [4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    slice(start?: number, end?: number): IIterableLinq<T>;
     /**
      * Runs the chain until its first value, then stops and closes the source.
      * @operation `Action`
@@ -1408,6 +1504,22 @@ export declare function override<K extends Extract<keyof IIterableLinq<unknown>,
  */
 export declare type Predicate<T> = (value: T, index: number) => boolean;
 
+/**
+ * Lazily yields `value`, then the values of `iterable`.
+ * `value` is yielded before the source is read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded before the first value of the source
+ * @returns a lazy, re-runnable `Iterable` of `value` followed by the values of the source
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.prepend([1, 2, 3], 0)); // [0, 1, 2, 3]
+ * ```
+ * @since 0.8.0
+ */
+declare function prepend<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Returns the numbers from 0 up to, but not including, `end`, computed as `index * step`.
  * The direction follows the sign of `end`; `reverse` yields the same numbers backwards; a `NaN` bound gives an empty `Iterable`.
@@ -1616,6 +1728,26 @@ declare function skip<T>(iterable: Iterable<T>, count: number): Iterable<T>;
  */
 declare function skipWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
 
+/**
+ * Lazily yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+ * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite source.
+ * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+ * A negative `start` reads the whole source before yielding, keeping only the last `-start` values.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param start - an integer, `0` by default; `-1` is the last value
+ * @param end - an integer; the values are yielded up to the end of the source by default
+ * @returns a lazy, re-runnable `Iterable` of the values from `start` to `end`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], 1, 3)); // [2, 3]
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], -2)); // [4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function slice<T>(iterable: Iterable<T>, start?: number, end?: number): Iterable<T>;
+
 /**
  * Tells whether `iterable` contains a value; reads one value, then closes the source.
  * @operation `Action`