@r01al/array-polyfills 1.0.3 → 1.0.7

package/dist/functions/compact.d.ts

@@ -0,0 +1,7 @@
+type Falsy = false | 0 | "" | null | undefined;
+/**
+ * Removes falsy values from the array.
+ * @returns A new array without falsy values.
+ */
+export default function <T>(this: T[]): Exclude<T, Falsy>[];
+export {};

package/dist/functions/compact.js

@@ -0,0 +1,7 @@
+/**
+ * Removes falsy values from the array.
+ * @returns A new array without falsy values.
+ */
+export default function () {
+    return this.filter((value) => Boolean(value));
+}

package/dist/functions/compactMap.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Maps items and removes null/undefined results.
+ * @param mapper Function to map items.
+ * @returns A new array of mapped values without null/undefined.
+ */
+export default function <T, R>(this: T[], mapper: (value: T, index: number, arr: T[]) => R): Exclude<R, null | undefined>[];

package/dist/functions/compactMap.js

@@ -0,0 +1,15 @@
+/**
+ * Maps items and removes null/undefined results.
+ * @param mapper Function to map items.
+ * @returns A new array of mapped values without null/undefined.
+ */
+export default function (mapper) {
+    const out = [];
+    for (let index = 0; index < this.length; index++) {
+        const value = mapper(this[index], index, this);
+        if (value !== null && value !== undefined) {
+            out.push(value);
+        }
+    }
+    return out;
+}

package/dist/functions/countBy.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Counts items by a key or mapper function.
+ * @param key The property name or mapper function to count by.
+ * @returns An object where keys are group identifiers and values are counts.
+ */
+export default function <T, K extends PropertyKey>(this: T[], key: ((item: T, index: number, arr: T[]) => K) | keyof T): Record<K, number>;

package/dist/functions/countBy.js

@@ -0,0 +1,17 @@
+/**
+ * Counts items by a key or mapper function.
+ * @param key The property name or mapper function to count by.
+ * @returns An object where keys are group identifiers and values are counts.
+ */
+export default function (key) {
+    const result = {};
+    const getKey = typeof key === "function"
+        ? key
+        : (item) => item[key];
+    for (let index = 0; index < this.length; index++) {
+        const item = this[index];
+        const groupKey = getKey(item, index, this);
+        result[groupKey] = (result[groupKey] ?? 0) + 1;
+    }
+    return result;
+}

package/dist/functions/difference.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns items that are not present in the other arrays.
+ * @param arrays Arrays to exclude.
+ * @returns A new array of values not found in other arrays.
+ */
+export default function <T>(this: T[], ...arrays: T[][]): T[];

package/dist/functions/difference.js

@@ -0,0 +1,15 @@
+/**
+ * Returns items that are not present in the other arrays.
+ * @param arrays Arrays to exclude.
+ * @returns A new array of values not found in other arrays.
+ */
+export default function (...arrays) {
+    if (arrays.length === 0)
+        return this.slice();
+    const other = new Set();
+    for (const arr of arrays) {
+        for (const item of arr)
+            other.add(item);
+    }
+    return this.filter(item => !other.has(item));
+}

package/dist/functions/flatten.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Flattens the array by one level.
+ * @returns A new flattened array.
+ */
+export default function <T>(this: (T | T[])[]): T[];

package/dist/functions/flatten.js

@@ -0,0 +1,14 @@
+/**
+ * Flattens the array by one level.
+ * @returns A new flattened array.
+ */
+export default function () {
+    const out = [];
+    for (const item of this) {
+        if (Array.isArray(item))
+            out.push(...item);
+        else
+            out.push(item);
+    }
+    return out;
+}

package/dist/functions/groupBy.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Groups array items by a key or mapper function.
+ * @param key The property name or mapper function to group by.
+ * @returns An object where keys are group identifiers and values are arrays of items.
+ */
+export default function <T, K extends PropertyKey>(this: T[], key: ((item: T, index: number, arr: T[]) => K) | keyof T): Record<K, T[]>;

package/dist/functions/groupBy.js

@@ -0,0 +1,19 @@
+/**
+ * Groups array items by a key or mapper function.
+ * @param key The property name or mapper function to group by.
+ * @returns An object where keys are group identifiers and values are arrays of items.
+ */
+export default function (key) {
+    const result = {};
+    const getKey = typeof key === "function"
+        ? key
+        : (item) => item[key];
+    for (let index = 0; index < this.length; index++) {
+        const item = this[index];
+        const groupKey = getKey(item, index, this);
+        if (!result[groupKey])
+            result[groupKey] = [];
+        result[groupKey].push(item);
+    }
+    return result;
+}

package/dist/functions/intersection.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns items present in all arrays.
+ * @param arrays Arrays to intersect with.
+ * @returns A new array of items found in every array.
+ */
+export default function <T>(this: T[], ...arrays: T[][]): T[];

package/dist/functions/intersection.js

@@ -0,0 +1,11 @@
+/**
+ * Returns items present in all arrays.
+ * @param arrays Arrays to intersect with.
+ * @returns A new array of items found in every array.
+ */
+export default function (...arrays) {
+    if (arrays.length === 0)
+        return this.slice();
+    const sets = arrays.map(arr => new Set(arr));
+    return this.filter(item => sets.every(set => set.has(item)));
+}

package/dist/functions/max.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the maximum number in the array.
+ * @returns The maximum value.
+ * @throws If any element is not a number.
+ */
+export default function (this: number[]): number | undefined;

package/dist/functions/max.js

@@ -0,0 +1,13 @@
+/**
+ * Returns the maximum number in the array.
+ * @returns The maximum value.
+ * @throws If any element is not a number.
+ */
+export default function () {
+    if (this.length === 0)
+        return undefined;
+    if (this.some(el => typeof el !== 'number')) {
+        throw new Error('All elements must be numbers');
+    }
+    return Math.max(...this);
+}

package/dist/functions/min.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns the minimum number in the array.
+ * @returns The minimum value.
+ * @throws If any element is not a number.
+ */
+export default function (this: number[]): number | undefined;

package/dist/functions/min.js

@@ -0,0 +1,13 @@
+/**
+ * Returns the minimum number in the array.
+ * @returns The minimum value.
+ * @throws If any element is not a number.
+ */
+export default function () {
+    if (this.length === 0)
+        return undefined;
+    if (this.some(el => typeof el !== 'number')) {
+        throw new Error('All elements must be numbers');
+    }
+    return Math.min(...this);
+}

package/dist/functions/pad.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Pads the array to the given length with the provided value.
+ * @param length Target length.
+ * @param value Value to pad with.
+ * @returns A new padded array.
+ */
+export default function <T>(this: T[], length: number, value: T): T[];

package/dist/functions/pad.js

@@ -0,0 +1,15 @@
+/**
+ * Pads the array to the given length with the provided value.
+ * @param length Target length.
+ * @param value Value to pad with.
+ * @returns A new padded array.
+ */
+export default function (length, value) {
+    if (!Number.isInteger(length) || length < 0) {
+        throw new Error("length must be a non-negative integer");
+    }
+    const out = this.slice();
+    while (out.length < length)
+        out.push(value);
+    return out;
+}

package/dist/functions/partition.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Splits the array into two arrays based on a predicate.
+ * @param predicate Function to test each element.
+ * @returns A tuple: [items that pass, items that fail].
+ */
+export default function <T>(this: T[], predicate: (value: T, index: number, arr: T[]) => boolean): [T[], T[]];

package/dist/functions/partition.js

@@ -0,0 +1,17 @@
+/**
+ * Splits the array into two arrays based on a predicate.
+ * @param predicate Function to test each element.
+ * @returns A tuple: [items that pass, items that fail].
+ */
+export default function (predicate) {
+    const pass = [];
+    const fail = [];
+    for (let index = 0; index < this.length; index++) {
+        const item = this[index];
+        if (predicate(item, index, this))
+            pass.push(item);
+        else
+            fail.push(item);
+    }
+    return [pass, fail];
+}

package/dist/functions/pluck.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Plucks a property from each item in the array.
+ * @param key Property name to pluck.
+ * @returns A new array of property values.
+ */
+export default function <T, K extends keyof T>(this: T[], key: K): T[K][];

package/dist/functions/pluck.js

@@ -0,0 +1,8 @@
+/**
+ * Plucks a property from each item in the array.
+ * @param key Property name to pluck.
+ * @returns A new array of property values.
+ */
+export default function (key) {
+    return this.map(item => item[key]);
+}

package/dist/functions/sample.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a random sample of items without replacement.
+ * @param count Number of items to sample.
+ * @returns A new array containing sampled items.
+ */
+export default function <T>(this: T[], count: number): T[];

package/dist/functions/sample.js

@@ -0,0 +1,16 @@
+/**
+ * Returns a random sample of items without replacement.
+ * @param count Number of items to sample.
+ * @returns A new array containing sampled items.
+ */
+export default function (count) {
+    if (!Number.isInteger(count) || count <= 0) {
+        throw new Error("count must be a positive integer");
+    }
+    const out = this.slice();
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [out[i], out[j]] = [out[j], out[i]];
+    }
+    return out.slice(0, Math.min(count, out.length));
+}

package/dist/functions/shuffle.d.ts

@@ -0,0 +1 @@
+export default function shuffle<T>(this: T[]): T[];

package/dist/functions/shuffle.js

@@ -0,0 +1,7 @@
+export default function shuffle() {
+    for (let i = this.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [this[i], this[j]] = [this[j], this[i]];
+    }
+    return this;
+}

package/dist/functions/sortBy.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sorts items by a key or mapper function (stable).
+ * @param key The property name or mapper function to sort by.
+ * @returns A new array sorted by the key.
+ */
+export default function <T, K extends string | number | bigint>(this: T[], key: ((item: T, index: number, arr: T[]) => K) | keyof T): T[];

package/dist/functions/sortBy.js

@@ -0,0 +1,20 @@
+/**
+ * Sorts items by a key or mapper function (stable).
+ * @param key The property name or mapper function to sort by.
+ * @returns A new array sorted by the key.
+ */
+export default function (key) {
+    const getKey = typeof key === "function"
+        ? key
+        : (item) => item[key];
+    return this
+        .map((item, index) => ({ item, index, key: getKey(item, index, this) }))
+        .sort((a, b) => {
+        if (a.key < b.key)
+            return -1;
+        if (a.key > b.key)
+            return 1;
+        return a.index - b.index;
+    })
+        .map(entry => entry.item);
+}

package/dist/functions/sum.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Calculates the sum of all numbers in an array.
+ * @returns The sum of all numbers in the array.
+ * @throws Will throw an error if any element in the array is not a number.
+ * @example
+ * [1, 2, 3].sum() // returns 6
+ * [10, -2, 5].sum() // returns 13
+ * [1, '2', 3].sum() // throws Error
+ */
+export default function <T>(this: T[]): number;

package/dist/functions/sum.js

@@ -0,0 +1,19 @@
+/**
+ * Calculates the sum of all numbers in an array.
+ * @returns The sum of all numbers in the array.
+ * @throws Will throw an error if any element in the array is not a number.
+ * @example
+ * [1, 2, 3].sum() // returns 6
+ * [10, -2, 5].sum() // returns 13
+ * [1, '2', 3].sum() // throws Error
+ */
+export default function () {
+    if (this.some(el => typeof el !== 'number')) {
+        throw new Error('All elements must be numbers');
+    }
+    let sum = 0;
+    for (const num of this) {
+        sum += num;
+    }
+    return sum;
+}

package/dist/functions/union.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns a unique merge of the array and the other arrays.
+ * @param arrays Arrays to merge.
+ * @returns A new array with unique values.
+ */
+export default function <T>(this: T[], ...arrays: T[][]): T[];

package/dist/functions/union.js

@@ -0,0 +1,22 @@
+/**
+ * Returns a unique merge of the array and the other arrays.
+ * @param arrays Arrays to merge.
+ * @returns A new array with unique values.
+ */
+export default function (...arrays) {
+    const out = [];
+    const seen = new Set();
+    const push = (item) => {
+        if (seen.has(item))
+            return;
+        seen.add(item);
+        out.push(item);
+    };
+    for (const item of this)
+        push(item);
+    for (const arr of arrays) {
+        for (const item of arr)
+            push(item);
+    }
+    return out;
+}

package/dist/functions/uniqBy.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns unique items by a key or mapper function.
+ * @param key The property name or mapper function to determine uniqueness.
+ * @returns A new array with unique items.
+ */
+export default function <T, K>(this: T[], key: ((item: T, index: number, arr: T[]) => K) | keyof T): T[];

package/dist/functions/uniqBy.js

@@ -0,0 +1,21 @@
+/**
+ * Returns unique items by a key or mapper function.
+ * @param key The property name or mapper function to determine uniqueness.
+ * @returns A new array with unique items.
+ */
+export default function (key) {
+    const result = [];
+    const seen = new Set();
+    const getKey = typeof key === "function"
+        ? key
+        : (item) => item[key];
+    for (let index = 0; index < this.length; index++) {
+        const item = this[index];
+        const keyValue = getKey(item, index, this);
+        if (!seen.has(keyValue)) {
+            seen.add(keyValue);
+            result.push(item);
+        }
+    }
+    return result;
+}

package/dist/functions/zip.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Zips the array with other arrays.
+ * @param arrays Arrays to zip with.
+ * @returns An array of tuples, truncated to the shortest length.
+ */
+export default function <T>(this: T[], ...arrays: any[][]): any[][];

package/dist/functions/zip.js

@@ -0,0 +1,15 @@
+/**
+ * Zips the array with other arrays.
+ * @param arrays Arrays to zip with.
+ * @returns An array of tuples, truncated to the shortest length.
+ */
+export default function (...arrays) {
+    if (arrays.length === 0)
+        return this.map(item => [item]);
+    const minLength = Math.min(this.length, ...arrays.map(arr => arr.length));
+    const out = [];
+    for (let index = 0; index < minLength; index++) {
+        out.push([this[index], ...arrays.map(arr => arr[index])]);
+    }
+    return out;
+}