@supercharge/arrays - npm Package Compare versions

Comparing version 1.2.0 to 2.0.0

dist/arr.d.ts

@@ -0,1 +1,2 @@
+declare type Values<T> = Array<T | Iterable<T> | undefined | null>;
 export declare class Arr<T> {
@@ -14,4 +15,28 @@ /**
      */
-    constructor(...values: T[] | T[][]);
+    constructor(...values: Values<T>);
     /**
+     * Creates an array from an iterable object.
+     *
+     * @param values  An iterable object to convert to an array.
+     */
+    static from<T>(...values: Values<T>): Arr<T>;
+    /**
+     * Determine whether the given `input` is an array.
+     *
+     * @param value - the `input` value to check whether it’s an array
+     */
+    static isIterable(value?: any): value is Iterable<any>;
+    /**
+     * Determine whether the given `input` is an array.
+     *
+     * @param input - the `input` value to check whether it’s an array
+     */
+    static isArray(input?: any): input is any[];
+    /**
+     * Determine whether the given `input` is not an array.
+     *
+     * @param input - the `input` value to check whether it’s not an array
+     */
+    static isNotArray<T>(input?: any[] | T): input is T;
+    /**
      * Returns the underlying, plain JavaScript array.
@@ -44,2 +69,10 @@ *
     /**
+     * Returns an array containing the concatenation of two or more values.
+     *
+     * @param {T[] | T[][]} values
+     *
+     * @returns {Arr}
+     */
+    concat(...values: Array<T | T[]>): Arr<T>;
+    /**
      * Breaks the array into multiple, smaller arrays
@@ -62,34 +95,4 @@ * of the given `size`.
     /**
-     * Creates an array of unique values that are included in both given array.
      *
-     * @param {Array} values
      *
-     * @returns {Arr}
-     */
-    intersect(values: T[]): Arr<T>;
-    /**
-     * Returns a new string by concatenating all of the elements in an array.
-     *
-     * @param {String} separator
-     *
-     * @returns {String}
-     */
-    join(separator: string): string;
-    /**
-     * Removes `undefined` and `null` values from the `array`.
-     *
-     * @returns {Arr}
-     */
-    removeNullish(): Arr<T>;
-    /**
-     * Returns an array containing the concatenation of two or more values.
-     *
-     * @param {T|T[]} values
-     *
-     * @returns {Arr}
-     */
-    concat(...values: T[]): Arr<T>;
-    /**
-     *
-     *
      * @param {Function} predicate
@@ -132,2 +135,28 @@ *
     /**
+     * Returns a new array instance containing the results of applying the
+     * given `transform` function to each item in the array. Ultimately,
+     * it flattens the mapped results one level deep.
+     *
+     * @param {Function} transform
+     *
+     * @returns {Array}
+     */
+    flatMap<R>(transform: (item: T, index: number, arr: Arr<T>) => R): Arr<R>;
+    /**
+     * Determine whether the array contains the given `value`.
+     *
+     * @param {*} value
+     *
+     * @returns {Boolean}
+     */
+    has(value: T): boolean;
+    /**
+     * Creates an array of unique values that are included in both given array.
+     *
+     * @param {Array} values
+     *
+     * @returns {Arr}
+     */
+    intersect(values: T[]): Arr<T>;
+    /**
      * Determine whether the array is empty.
@@ -139,2 +168,10 @@ *
     /**
+     * Determine whether the array does not contain the given `value`.
+     *
+     * @param {*} value
+     *
+     * @returns {Boolean}
+     */
+    isMissing(value: T): boolean;
+    /**
      * Determine whether the array is not empty.
@@ -146,2 +183,10 @@ *
     /**
+     * Returns a new string by concatenating all of the elements in an array.
+     *
+     * @param {String} separator
+     *
+     * @returns {String}
+     */
+    join(separator: string): string;
+    /**
      * Returns the last element of the array or returns the last item in the array matching
@@ -163,2 +208,11 @@ * the given `predicate` function. Returns `undefined` if no matching item is found or
     /**
+     * Returns a new array instance containing the results after applying
+     * the given `transform` function to each item in the array.
+     *
+     * @param {Function} transform
+     *
+     * @returns {Arr<R>}
+     */
+    map<R>(transform: (item: T, index: number, arr: Arr<T>) => R): Arr<R>;
+    /**
      * Returns the max value in the array.
@@ -186,5 +240,3 @@ *
      *
-     * @param {}
-     *
-     * @returns {(T|undefined)}
+     * @returns {T|undefined}
      */
@@ -197,4 +249,18 @@ pop(): T | undefined;
      */
-    push(...values: T[]): Arr<T>;
+    push(...values: Values<T>): this;
     /**
+     * Returns a flat array of items removing `undefined` and `null` values.
+     *
+     * @param values
+     *
+     * @returns {T[]}
+     */
+    private resolveValues;
+    /**
+     * Removes `undefined` and `null` values from the array.
+     *
+     * @returns {Arr}
+     */
+    removeNullish(): Arr<T>;
+    /**
     * Returns reversed version of original array.
@@ -212,2 +278,8 @@ *
     /**
+     * Returns the number of items in the array. This method is an alias for `.length()`.
+     *
+     * @returns {Number}
+     */
+    size(): number;
+    /**
      * Returns a chunk of items beginning at the `start`
@@ -236,8 +308,2 @@ * index without removing them from the array.
     /**
-     * Returns the number of items in the array. This method is an alias for `.length()`.
-     *
-     * @returns {Number}
-     */
-    size(): number;
-    /**
      * Returns a sorted array of items, with an optional comparator.
@@ -280,1 +346,2 @@ *
 }
+export {};

dist/arr.js

@@ -14,5 +14,38 @@ 'use strict';
     constructor(...values) {
-        this.values = [].concat(...values);
+        this.values = [];
+        this.push(...values);
     }
     /**
+     * Creates an array from an iterable object.
+     *
+     * @param values  An iterable object to convert to an array.
+     */
+    static from(...values) {
+        return new this(...values);
+    }
+    /**
+     * Determine whether the given `input` is an array.
+     *
+     * @param value - the `input` value to check whether it’s an array
+     */
+    static isIterable(value) {
+        return Array.from(value).length > 0;
+    }
+    /**
+     * Determine whether the given `input` is an array.
+     *
+     * @param input - the `input` value to check whether it’s an array
+     */
+    static isArray(input) {
+        return Array.isArray(input);
+    }
+    /**
+     * Determine whether the given `input` is not an array.
+     *
+     * @param input - the `input` value to check whether it’s not an array
+     */
+    static isNotArray(input) {
+        return !this.isArray(input);
+    }
+    /**
      * Returns the underlying, plain JavaScript array.
@@ -60,2 +93,12 @@ *
     /**
+     * Returns an array containing the concatenation of two or more values.
+     *
+     * @param {T[] | T[][]} values
+     *
+     * @returns {Arr}
+     */
+    concat(...values) {
+        return new Arr(...this.values.concat(...values));
+    }
+    /**
      * Breaks the array into multiple, smaller arrays
@@ -85,42 +128,2 @@ * of the given `size`.
     }
-    /**
-     * Creates an array of unique values that are included in both given array.
-     *
-     * @param {Array} values
-     *
-     * @returns {Arr}
-     */
-    intersect(values) {
-        return new Arr(...new Set(this.values.filter((value) => values.includes(value))));
-    }
-    /**
-     * Returns a new string by concatenating all of the elements in an array.
-     *
-     * @param {String} separator
-     *
-     * @returns {String}
-     */
-    join(separator) {
-        return this.values.join(separator);
-    }
-    /**
-     * Removes `undefined` and `null` values from the `array`.
-     *
-     * @returns {Arr}
-     */
-    removeNullish() {
-        return this
-            .filter((item) => item !== null)
-            .filter((item) => item !== undefined);
-    }
-    /**
-     * Returns an array containing the concatenation of two or more values.
-     *
-     * @param {T|T[]} values
-     *
-     * @returns {Arr}
-     */
-    concat(...values) {
-        return new Arr(...this.values, ...values);
-    }
     filter(predicate) {
@@ -151,2 +154,38 @@ const arr = new Arr();
     /**
+     * Returns a new array instance containing the results of applying the
+     * given `transform` function to each item in the array. Ultimately,
+     * it flattens the mapped results one level deep.
+     *
+     * @param {Function} transform
+     *
+     * @returns {Array}
+     */
+    flatMap(transform) {
+        return this.map((item, index) => {
+            return transform(item, index, this);
+        }).collapse();
+    }
+    /**
+     * Determine whether the array contains the given `value`.
+     *
+     * @param {*} value
+     *
+     * @returns {Boolean}
+     */
+    has(value) {
+        return this
+            .filter(item => item === value)
+            .length() > 0;
+    }
+    /**
+     * Creates an array of unique values that are included in both given array.
+     *
+     * @param {Array} values
+     *
+     * @returns {Arr}
+     */
+    intersect(values) {
+        return new Arr(...new Set(this.values.filter((value) => values.includes(value))));
+    }
+    /**
      * Determine whether the array is empty.
@@ -160,2 +199,12 @@ *
     /**
+     * Determine whether the array does not contain the given `value`.
+     *
+     * @param {*} value
+     *
+     * @returns {Boolean}
+     */
+    isMissing(value) {
+        return !this.has(value);
+    }
+    /**
      * Determine whether the array is not empty.
@@ -169,2 +218,12 @@ *
     /**
+     * Returns a new string by concatenating all of the elements in an array.
+     *
+     * @param {String} separator
+     *
+     * @returns {String}
+     */
+    join(separator) {
+        return this.values.join(separator);
+    }
+    /**
      * Returns the last element of the array or returns the last item in the array matching
@@ -192,2 +251,15 @@ * the given `predicate` function. Returns `undefined` if no matching item is found or
     /**
+     * Returns a new array instance containing the results after applying
+     * the given `transform` function to each item in the array.
+     *
+     * @param {Function} transform
+     *
+     * @returns {Arr<R>}
+     */
+    map(transform) {
+        return Arr.from(this.toArray().map((value, index) => {
+            return transform(value, index, this);
+        }));
+    }
+    /**
      * Returns the max value in the array.
@@ -198,3 +270,3 @@ *
     max() {
-        return Math.max(...this.values.map((value) => +value));
+        return Math.max(...this.values.map(value => +value));
     }
@@ -226,5 +298,3 @@ /**
      *
-     * @param {}
-     *
-     * @returns {(T|undefined)}
+     * @returns {T|undefined}
      */
@@ -240,6 +310,39 @@ pop() {
     push(...values) {
-        this.values.push(...values);
+        for (const value of this.resolveValues(...values)) {
+            this.values.push(value);
+        }
         return this;
     }
     /**
+     * Returns a flat array of items removing `undefined` and `null` values.
+     *
+     * @param values
+     *
+     * @returns {T[]}
+     */
+    resolveValues(...values) {
+        return values.flatMap(value => {
+            if (value === null || value === undefined) {
+                return value;
+            }
+            if (Array.isArray(value)) {
+                return value;
+            }
+            if (Arr.isIterable(value)) {
+                return Array.from(value);
+            }
+            return [].concat(value);
+        });
+    }
+    /**
+     * Removes `undefined` and `null` values from the array.
+     *
+     * @returns {Arr}
+     */
+    removeNullish() {
+        return this.filter(item => {
+            return item !== null && item !== undefined;
+        });
+    }
+    /**
     * Returns reversed version of original array.
@@ -261,2 +364,10 @@ *
     /**
+     * Returns the number of items in the array. This method is an alias for `.length()`.
+     *
+     * @returns {Number}
+     */
+    size() {
+        return this.length();
+    }
+    /**
      * Returns a chunk of items beginning at the `start`
@@ -292,10 +403,2 @@ * index without removing them from the array.
     /**
-     * Returns the number of items in the array. This method is an alias for `.length()`.
-     *
-     * @returns {Number}
-     */
-    size() {
-        return this.length();
-    }
-    /**
      * Returns a sorted array of items, with an optional comparator.
@@ -302,0 +405,0 @@ *

dist/index.d.ts

@@ -1,11 +0,3 @@
-import { ArrContract } from './arr-contract';
-/**
- * Creates a new  providing chainable string operations. This new
- * instance clones the original string and works with the clone.
- * It won’t modify the original string value.
- *
- * @param {*} values
- */
-declare const arr: ArrContract;
-export default arr;
-export declare const Arr: ArrContract;
+export * from './arr';
+declare const _default: "./arr";
+export default _default;

dist/index.js

 'use strict';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Arr = void 0;
-const arr_1 = require("./arr");
-/**
- * Creates a new  providing chainable string operations. This new
- * instance clones the original string and works with the clone.
- * It won’t modify the original string value.
- *
- * @param {*} values
- */
-const arr = function (...values) {
-    return new arr_1.Arr(...values).removeNullish();
-};
-function from(iterable, mapfn, thisArg) {
-    iterable = iterable !== null && iterable !== void 0 ? iterable : [];
-    const values = mapfn ? Array.from(iterable, mapfn, thisArg) : Array.from(iterable);
-    return new arr_1.Arr(values);
-}
-/**
- * Determine whether the given `input` is an array.
- *
- * @param input - the `input` value to check whether it’s an array
- */
-function isArray(input) {
-    return Array.isArray(input);
-}
-/**
- * Determine whether the given `input` is not an array.
- *
- * @param input - the `input` value to check whether it’s not an array
- */
-function isNotArray(input) {
-    return !arr.isArray(input);
-}
-arr.from = from;
-arr.isArray = isArray;
-arr.isNotArray = isNotArray;
-exports.default = arr;
-exports.Arr = arr;
+__exportStar(require("./arr"), exports);
+exports.default = './arr';

package.json

 {
   "name": "@supercharge/arrays",
   "description": "Array utilities for Node.js and JavaScript",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "author": "Marcus Pöhls <[e-mail]>",
@@ -6,0 +6,0 @@ "bugs": {

README.md

@@ -33,3 +33,3 @@ <div align="center">
 ## Introduction
-The `@supercharge/arrays` package provides chainable array utilities for Node.js and JavaScript. It’s a wrapper around JavaScript arrays providing useful methods like `.isEmpty()`, `.size()`, `.flatMap()`, `.contains()`, and many more.
+The `@supercharge/arrays` package provides chainable array utilities for Node.js and JavaScript. It’s a wrapper around JavaScript arrays providing useful methods like `.isEmpty()`, `.length()`, `.flatMap()`, `.contains()`, and many more.
 
@@ -54,16 +54,27 @@
 
-const hasItemsGreaterTen = Arr([1, 2, 3, 4, 5, 6])
-  .map(value => value * 2) // [2, 4, 6, 8, 10, 12]
-  .filter(value => value > 10) // [12]
-  .isNotEmpty() // true
+const users = Arr.from([])
 
+users.isEmpty()
+// true
 
-// Only methods, no properties
-Arr([1, 2, 3]).length() // 3
+users
+  .push({ id: 1, name: 'Marcus' })
+  .push({ id: 2, name: 'Norman' })
+  .push({ id: 3, name: 'Christian' })
 
+users.isNotEmpty()
+// true
 
-// Supports callbacks for `.includes`:
-Arr([1, 2, 3]).includes(value => {
-  return value > 2
+users.length()
+// 3
+
+const usernamesArray = users
+  .map(user => user.name)
+  .toArray()
+// [ 'Marcus', 'Norman', 'Christian' ]
+
+const marcus = users.find(user => {
+  return user.name === 'Marcus'
 })
+// { id: 1, name: 'Marcus' }
 ```
@@ -70,0 +81,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

27793

increased by17.9%

Lines of code

834

increased by19.48%

Number of lines in readme file

101

increased by12.22%

No dependency changes