Functional extension methods (inspired by LINQ .NET) on JavaScript arrays


Keywords
functional, linq, array
License
MIT
Install
npm install array-x@3.0.1

Documentation

array-x.js

Functional methods (inspired by LINQ) on JavaScript arrays

Examples

var ArrayX: typeof X.Array = require("array-x");

var arr = new ArrayX<any>(
    new Date("March 21, 2020"),
    /abc[.]+/g,
    "a", "b", "c",
    1, 2, 3, 4, 5, 6, 7,
    [
        0,
        1
    ],
    [
        2,
        3
    ],
    [
        4,
        5,
        [
            6,
            7,
            [
                8,
                [
                    9,
                    10
                ]
            ]
        ]
    ],
    "last"
);

console.log("first(): " + arr.first());
console.log("last(): " + arr.last());
console.log("skip(2): " + arr.skip(2));
console.log("where(x=>x>3):" + arr.where(x => x > 3));
console.log("select(x=>x.length): " + arr.select(x => x.length));
console.log("flatten(): " + arr.flatten());
console.log("append(): " + arr.append(["a", "b", "c"]));

Output:

first(): Sat Mar 21 2020 00:00:00 GMT-0700 (Pacific Daylight Time)
last(): last
skip(2): a,b,c,1,2,3,4,5,6,7,0,1,2,3,4,5,6,7,8,9,10,last
where(x=>x>3):Sat Mar 21 2020 00:00:00 GMT-0700 (Pacific Daylight Time),4,5,6,7
select(x=>x.length): ,,1,1,1,,,,,,,,2,2,3,4
flatten(): Sat Mar 21 2020 00:00:00 GMT-0700 (Pacific Daylight Time),/abc[.]+/g,a,b,c,1,2,3,4,5,6,7,0,1,2,3,4,5,6,7,8,9,10,last
append(): Sat Mar 21 2020 00:00:00 GMT-0700 (Pacific Daylight Time),/abc[.]+/g,a,b,c,1,2,3,4,5,6,7,0,1,2,3,4,5,6,7,8,9,10,last,a,b,c

API

declare namespace X {
    type Func = (value: any, index?: number) => any
    type Predicate = (value: any, index?: number) => boolean
    type Accumulator = (accumulatedValue: any, currentValue: any, index?: number) => any
    type Dictionary<T> = { [key: string]: T }

    class Array<T> implements ArrayLike<T> {
        constructor(...items: T[]);

        distinct(): Array<T>;
        accumulate(initial: any, accum?: Accumulator): any;
        union(array: Array<any>): Array<T>;

        select(func?: Func): Array<T>;
        where(func?: Predicate): Array<T>;

        orderBy(func?: Func): Array<T>;
        orderByDesc(func: Func): Array<T>;

        firstOrDefault(predicate?: Predicate): T;
        first(predicate?: Predicate): T;

        lastOrDefault(predicate?: Predicate): T;
        last(predicate?: Predicate): T;

        all(predicate?: Predicate): boolean;
        any(predicate?: Predicate): boolean;

        take(count: number): Array<T>;
        skip(count: number): Array<T>;

        sum(func?: Func): number;
        avg(func?: Func): number;
        count(func?: Func): number;
        min(func?: Func): number;
        max(func?: Func): number;

        /* 
         * Groups the array values into a dictionary of arrays. 
         * Grouping keys are determined by applying the <func> function arg to each element 
         */
        groupBy(func?: Func): X.Dictionary<X.Array<T>>;

        /* 
         * Groups this array into an dictionary of <keyCount> arrays,
         * each containing the same number of elements, except possibly the last array, 
         * which may have less elements than the others 
         * if the length of this array is not divisible by <keyCount>
         */
        groupByNumber(keyCount: number): X.Dictionary<X.Array<T>>;

        /*
         * groups this array according to <key> generator function and then 
         * aggregates the resulting dictionary over <value> generator function
         */
        groupAggregate(
            key: string | X.Func,
            value: string | X.Func,
            aggregation: "min" | "max" | "sum" | "avg" | "count")
            : X.Dictionary<number>;

        removeItem(item: any): Array<T>;
        removeAt(index: number, count?: number): Array<T>;
        insert(index: number, ...items: any[]): Array<T>;
        append(...items: any[]): Array<T>;

        flatten(): Array<T>;

        /**
         * Determines whether an array includes a certain element, returning true or false as appropriate.
         * @param searchElement The element to search for.
         * @param fromIndex The position in this array at which to begin searching for searchElement.
         */
        contains(obj: T, fromIndex?: number): boolean;

        static fromSize(size?: number): Array<any>;
        static fromRange(from: number, to: number): Array<any>;

        /**
         * Gets the length of the array. This is a number one higher than the highest element defined in an array.
         */
        readonly length: number;
        readonly [n: number]: T;
    }

}

Install

npm install array-x --save