iterable-linq-utility 0.5.0 → 0.6.0

package/dist/index.d.cts

@@ -15,6 +15,24 @@ export declare type Action<T> = (value: T, index: number) => Unit;
  */
 export declare type AsyncAction<T> = (value: T, index: number) => Promise<Unit>;
 
+/**
+ * Returns the value at `index`, like `Array.prototype.at`; a negative index counts from the end.
+ * A non-negative index reads up to the value, then closes the source; a negative index reads the whole source,
+ * keeping only the last `-index` values.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param index - an integer; `-1` is the last value
+ * @returns the value at `index`, or `undefined` if `iterable` has no value there
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `index` is not an integer (fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Functions.at([10, 20, 30], 1); // 20
+ * Functions.at([10, 20, 30], -1); // 30
+ * ```
+ * @since 0.6.0
+ */
+declare function at<T>(iterable: Iterable<T>, index: number): T | undefined;
+
 /**
  * Implementation of a method added with `extend` or `override`. `this` is the chain the method is called on.
  * @since 0.1.0
@@ -241,6 +259,55 @@ declare function find<T>(iterable: Iterable<T>, predicate: Predicate<T>): T | un
  */
 declare function findIndex<T>(iterable: Iterable<T>, predicate: Predicate<T>): number;
 
+/**
+ * Returns the last value accepted by a type guard, narrowing its type; reads the whole source.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - a type guard called with each value and its index
+ * @returns the last value accepted by `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * const values: (number | string)[] = [1, 'two', 3, 'four'];
+ * Functions.findLast(values, (v): v is string => typeof v === 'string'); // string | undefined, 'four'
+ * ```
+ * @since 0.6.0
+ */
+declare function findLast<T, S extends T>(iterable: Iterable<T>, predicate: (value: T, index: number) => value is S): S | undefined;
+
+/**
+ * Returns the last value that satisfies `predicate`; reads the whole source.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index
+ * @returns the last value that satisfies `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.findLast([1, 5, 6, 2], v => v > 4); // 6
+ * ```
+ * @since 0.6.0
+ */
+declare function findLast<T>(iterable: Iterable<T>, predicate: Predicate<T>): T | undefined;
+
+/**
+ * Returns the index of the last value that satisfies `predicate`; reads the whole source.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index
+ * @returns the index of the last value that satisfies `predicate`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.findLastIndex([1, 5, 6, 2], v => v > 4); // 2
+ * ```
+ * @since 0.6.0
+ */
+declare function findLastIndex<T>(iterable: Iterable<T>, predicate: Predicate<T>): number;
+
 /**
  * Lazily maps each value to an `Iterable` and flattens the results.
  * Each inner `Iterable` is read completely before the next value is mapped.
@@ -353,6 +420,7 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 
 declare namespace Functions {
     export {
+        at,
         collectToArray,
         count,
         distinct,
@@ -361,10 +429,14 @@ declare namespace Functions {
         filter,
         find,
         findIndex,
+        findLast,
+        findLastIndex,
         flatMap,
         forEach,
         forEachAsync,
         includes,
+        indexOf,
+        lastIndexOf,
         map,
         materialize,
         max,
@@ -420,6 +492,22 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * 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,
+     * keeping only the last `-index` values.
+     * @operation `Action`
+     * @param index - an integer; `-1` is the last value
+     * @returns the value at `index`, or `undefined` if the chain has no value there
+     * @throws Error if `index` is not an integer (fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([10, 20, 30]).at(1); // 20
+     * IterableLinq.from([10, 20, 30]).at(-1); // 30
+     * ```
+     * @since 0.6.0
+     */
+    at(index: number): T | undefined;
     /**
      * Runs the chain and collects its values into an `Array`.
      * @operation `Action`
@@ -554,6 +642,49 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     findIndex(predicate: Predicate<T>): number;
+    /**
+     * Returns the last value accepted by a type guard, narrowing its type; runs the whole chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - a type guard called with each value and its index
+     * @returns the last value accepted by `predicate`, or `undefined` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * const values: (number | string)[] = [1, 'two', 3, 'four'];
+     * IterableLinq.from(values).findLast((v): v is string => typeof v === 'string'); // string | undefined, 'four'
+     * ```
+     * @since 0.6.0
+     */
+    findLast<S extends T>(predicate: (value: T, index: number) => value is S): S | undefined;
+    /**
+     * Returns the last value that satisfies `predicate`; runs the whole chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns the last value that satisfies `predicate`, or `undefined` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 6, 2]).findLast(v => v > 4); // 6
+     * ```
+     * @since 0.6.0
+     */
+    findLast(predicate: Predicate<T>): T | undefined;
+    /**
+     * Returns the index of the last value that satisfies `predicate`; runs the whole chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns the index of the last value that satisfies `predicate`, or `-1` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 6, 2]).findLastIndex(v => v > 4); // 2
+     * ```
+     * @since 0.6.0
+     */
+    findLastIndex(predicate: Predicate<T>): number;
     /**
      * Maps each value to an `Iterable` and flattens the results into one chain.
      * Each inner `Iterable` is read completely before the next value of the chain is mapped.
@@ -618,6 +749,32 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     includes(value: T): boolean;
+    /**
+     * Returns the index of the first value strictly equal (`===`) to `value`, like `Array.prototype.indexOf`;
+     * stops and closes the source at the first match.
+     * @operation `Action`
+     * @param value - the value to look for; `NaN` is never found, use `includes` or `findIndex` for it
+     * @returns the index of the first value equal to `value`, or `-1` if there is none
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 2]).indexOf(2); // 1
+     * ```
+     * @since 0.6.0
+     */
+    indexOf(value: T): number;
+    /**
+     * Returns the index of the last value strictly equal (`===`) to `value`, like `Array.prototype.lastIndexOf`;
+     * runs the whole chain.
+     * @operation `Action`
+     * @param value - the value to look for; `NaN` is never found, use `findLastIndex` for it
+     * @returns the index of the last value equal to `value`, or `-1` if there is none
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 2]).lastIndexOf(2); // 3
+     * ```
+     * @since 0.6.0
+     */
+    lastIndexOf(value: T): number;
     /**
      * Transforms each value with `mapper`.
      * If `mapper` throws, the source is closed and the error propagates.
@@ -895,6 +1052,22 @@ export declare interface IMemoizeOptions {
  */
 declare function includes<T>(iterable: Iterable<T>, value: T): boolean;
 
+/**
+ * Returns the index of the first value strictly equal (`===`) to `value`, like `Array.prototype.indexOf`;
+ * stops and closes the source at the first match.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param value - the value to look for; `NaN` is never found, use `includes` or `findIndex` for it
+ * @returns the index of the first value equal to `value`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.indexOf([1, 2, 3, 2], 2); // 1
+ * ```
+ * @since 0.6.0
+ */
+declare function indexOf<T>(iterable: Iterable<T>, value: T): number;
+
 /**
  * Options of `range`.
  * @since 0.1.0
@@ -921,6 +1094,22 @@ export declare interface IRangeOptions {
  */
 export declare function isIterableLinq(value: unknown): value is IIterableLinq<unknown>;
 
+/**
+ * Returns the index of the last value strictly equal (`===`) to `value`, like `Array.prototype.lastIndexOf`;
+ * reads the whole source.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param value - the value to look for; `NaN` is never found, use `findLastIndex` for it
+ * @returns the index of the last value equal to `value`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.lastIndexOf([1, 2, 3, 2], 2); // 3
+ * ```
+ * @since 0.6.0
+ */
+declare function lastIndexOf<T>(iterable: Iterable<T>, value: T): number;
+
 /**
  * Lazily transforms each value with `mapper`.
  * If `mapper` throws, the source is closed and the error propagates.

package/dist/index.d.ts

@@ -15,6 +15,24 @@ export declare type Action<T> = (value: T, index: number) => Unit;
  */
 export declare type AsyncAction<T> = (value: T, index: number) => Promise<Unit>;
 
+/**
+ * Returns the value at `index`, like `Array.prototype.at`; a negative index counts from the end.
+ * A non-negative index reads up to the value, then closes the source; a negative index reads the whole source,
+ * keeping only the last `-index` values.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param index - an integer; `-1` is the last value
+ * @returns the value at `index`, or `undefined` if `iterable` has no value there
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `index` is not an integer (fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Functions.at([10, 20, 30], 1); // 20
+ * Functions.at([10, 20, 30], -1); // 30
+ * ```
+ * @since 0.6.0
+ */
+declare function at<T>(iterable: Iterable<T>, index: number): T | undefined;
+
 /**
  * Implementation of a method added with `extend` or `override`. `this` is the chain the method is called on.
  * @since 0.1.0
@@ -241,6 +259,55 @@ declare function find<T>(iterable: Iterable<T>, predicate: Predicate<T>): T | un
  */
 declare function findIndex<T>(iterable: Iterable<T>, predicate: Predicate<T>): number;
 
+/**
+ * Returns the last value accepted by a type guard, narrowing its type; reads the whole source.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - a type guard called with each value and its index
+ * @returns the last value accepted by `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * const values: (number | string)[] = [1, 'two', 3, 'four'];
+ * Functions.findLast(values, (v): v is string => typeof v === 'string'); // string | undefined, 'four'
+ * ```
+ * @since 0.6.0
+ */
+declare function findLast<T, S extends T>(iterable: Iterable<T>, predicate: (value: T, index: number) => value is S): S | undefined;
+
+/**
+ * Returns the last value that satisfies `predicate`; reads the whole source.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index
+ * @returns the last value that satisfies `predicate`, or `undefined` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.findLast([1, 5, 6, 2], v => v > 4); // 6
+ * ```
+ * @since 0.6.0
+ */
+declare function findLast<T>(iterable: Iterable<T>, predicate: Predicate<T>): T | undefined;
+
+/**
+ * Returns the index of the last value that satisfies `predicate`; reads the whole source.
+ * If `predicate` throws, the source is closed and the error propagates.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param predicate - called with each value and its index
+ * @returns the index of the last value that satisfies `predicate`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `predicate` is not a function
+ * @example
+ * ```ts
+ * Functions.findLastIndex([1, 5, 6, 2], v => v > 4); // 2
+ * ```
+ * @since 0.6.0
+ */
+declare function findLastIndex<T>(iterable: Iterable<T>, predicate: Predicate<T>): number;
+
 /**
  * Lazily maps each value to an `Iterable` and flattens the results.
  * Each inner `Iterable` is read completely before the next value is mapped.
@@ -353,6 +420,7 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 
 declare namespace Functions {
     export {
+        at,
         collectToArray,
         count,
         distinct,
@@ -361,10 +429,14 @@ declare namespace Functions {
         filter,
         find,
         findIndex,
+        findLast,
+        findLastIndex,
         flatMap,
         forEach,
         forEachAsync,
         includes,
+        indexOf,
+        lastIndexOf,
         map,
         materialize,
         max,
@@ -420,6 +492,22 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * 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,
+     * keeping only the last `-index` values.
+     * @operation `Action`
+     * @param index - an integer; `-1` is the last value
+     * @returns the value at `index`, or `undefined` if the chain has no value there
+     * @throws Error if `index` is not an integer (fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([10, 20, 30]).at(1); // 20
+     * IterableLinq.from([10, 20, 30]).at(-1); // 30
+     * ```
+     * @since 0.6.0
+     */
+    at(index: number): T | undefined;
     /**
      * Runs the chain and collects its values into an `Array`.
      * @operation `Action`
@@ -554,6 +642,49 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     findIndex(predicate: Predicate<T>): number;
+    /**
+     * Returns the last value accepted by a type guard, narrowing its type; runs the whole chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - a type guard called with each value and its index
+     * @returns the last value accepted by `predicate`, or `undefined` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * const values: (number | string)[] = [1, 'two', 3, 'four'];
+     * IterableLinq.from(values).findLast((v): v is string => typeof v === 'string'); // string | undefined, 'four'
+     * ```
+     * @since 0.6.0
+     */
+    findLast<S extends T>(predicate: (value: T, index: number) => value is S): S | undefined;
+    /**
+     * Returns the last value that satisfies `predicate`; runs the whole chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns the last value that satisfies `predicate`, or `undefined` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 6, 2]).findLast(v => v > 4); // 6
+     * ```
+     * @since 0.6.0
+     */
+    findLast(predicate: Predicate<T>): T | undefined;
+    /**
+     * Returns the index of the last value that satisfies `predicate`; runs the whole chain.
+     * If `predicate` throws, the source is closed and the error propagates.
+     * @operation `Action`
+     * @param predicate - called with each value and its index
+     * @returns the index of the last value that satisfies `predicate`, or `-1` if there is none
+     * @throws Error if `predicate` is not a function
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 5, 6, 2]).findLastIndex(v => v > 4); // 2
+     * ```
+     * @since 0.6.0
+     */
+    findLastIndex(predicate: Predicate<T>): number;
     /**
      * Maps each value to an `Iterable` and flattens the results into one chain.
      * Each inner `Iterable` is read completely before the next value of the chain is mapped.
@@ -618,6 +749,32 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     includes(value: T): boolean;
+    /**
+     * Returns the index of the first value strictly equal (`===`) to `value`, like `Array.prototype.indexOf`;
+     * stops and closes the source at the first match.
+     * @operation `Action`
+     * @param value - the value to look for; `NaN` is never found, use `includes` or `findIndex` for it
+     * @returns the index of the first value equal to `value`, or `-1` if there is none
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 2]).indexOf(2); // 1
+     * ```
+     * @since 0.6.0
+     */
+    indexOf(value: T): number;
+    /**
+     * Returns the index of the last value strictly equal (`===`) to `value`, like `Array.prototype.lastIndexOf`;
+     * runs the whole chain.
+     * @operation `Action`
+     * @param value - the value to look for; `NaN` is never found, use `findLastIndex` for it
+     * @returns the index of the last value equal to `value`, or `-1` if there is none
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 2]).lastIndexOf(2); // 3
+     * ```
+     * @since 0.6.0
+     */
+    lastIndexOf(value: T): number;
     /**
      * Transforms each value with `mapper`.
      * If `mapper` throws, the source is closed and the error propagates.
@@ -895,6 +1052,22 @@ export declare interface IMemoizeOptions {
  */
 declare function includes<T>(iterable: Iterable<T>, value: T): boolean;
 
+/**
+ * Returns the index of the first value strictly equal (`===`) to `value`, like `Array.prototype.indexOf`;
+ * stops and closes the source at the first match.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param value - the value to look for; `NaN` is never found, use `includes` or `findIndex` for it
+ * @returns the index of the first value equal to `value`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.indexOf([1, 2, 3, 2], 2); // 1
+ * ```
+ * @since 0.6.0
+ */
+declare function indexOf<T>(iterable: Iterable<T>, value: T): number;
+
 /**
  * Options of `range`.
  * @since 0.1.0
@@ -921,6 +1094,22 @@ export declare interface IRangeOptions {
  */
 export declare function isIterableLinq(value: unknown): value is IIterableLinq<unknown>;
 
+/**
+ * Returns the index of the last value strictly equal (`===`) to `value`, like `Array.prototype.lastIndexOf`;
+ * reads the whole source.
+ * @operation `Action`
+ * @param iterable - the source `Iterable`
+ * @param value - the value to look for; `NaN` is never found, use `findLastIndex` for it
+ * @returns the index of the last value equal to `value`, or `-1` if there is none
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Functions.lastIndexOf([1, 2, 3, 2], 2); // 3
+ * ```
+ * @since 0.6.0
+ */
+declare function lastIndexOf<T>(iterable: Iterable<T>, value: T): number;
+
 /**
  * Lazily transforms each value with `mapper`.
  * If `mapper` throws, the source is closed and the error propagates.