@stacksjs/arrays 0.58.73 → 0.59.2

package/dist/arr.d.ts

@@ -0,0 +1,3 @@
+export * from './helpers';
+export * from './math';
+export * from './contains';

package/dist/contains.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Returns true if the needle is contained in the haystack.
+ *
+ * @param needle
+ * @param haystack
+ * @example
+ * ```ts
+ * contains('foo', ['foo', 'bar']) // true
+ * contains('foo', ['bar']) // false
+ * ```
+ */
+export declare function contains(needle: string, haystack: string[]): boolean;
+/**
+ * Returns true if all needles are contained in the haystack.
+ * @param needles
+ * @param haystack
+ * @example
+ * ```ts
+ * containsAll(['foo', 'bar'], ['foo', 'bar', 'baz']) // true
+ * containsAll(['foo', 'bar'], ['foo', 'baz']) // false
+ * ```
+ */
+export declare function containsAll(needles: string[], haystack: string[]): boolean;
+/**
+ * Returns true if any needle is contained in the haystack.
+ * @param needles
+ * @param haystack
+ * @example
+ * ```ts
+ * containsAny(['foo', 'bar'], ['foo', 'bar', 'baz']) // true
+ * containsAny(['foo', 'bar'], ['foo', 'baz']) // true
+ * containsAny(['foo', 'bar'], ['baz']) // false
+ * ```
+ */
+export declare function containsAny(needles: string[], haystack: string[]): boolean;
+/**
+ * Returns true if none of the needles are contained in the haystack.
+ * @param needles
+ * @param haystack
+ * @example
+ * ```ts
+ * containsNone(['foo', 'bar'], ['foo', 'bar', 'baz']) // false
+ * containsNone(['foo', 'bar'], ['foo', 'baz']) // false
+ * containsNone(['foo', 'bar'], ['baz']) // true
+ * ```
+ */
+export declare function containsNone(needles: string[], haystack: string[]): boolean;
+/**
+ * Returns true if all needles are contained in the haystack.
+ * @param needles
+ * @param haystack
+ * @example
+ * ```ts
+ * containsOnly(['foo', 'bar'], ['foo', 'bar', 'baz']) // false
+ * containsOnly(['foo', 'bar'], ['foo', 'baz']) // false
+ * containsOnly(['foo', 'bar'], ['foo', 'bar']) // true
+ * ```
+ */
+export declare function containsOnly(needles: string[], haystack: string[]): boolean;
+/**
+ * Returns true if the needle is not contained in the haystack.
+ * @param needle
+ * @param haystack
+ * @example
+ * ```ts
+ * doesNotContain('foo', ['foo', 'bar']) // false
+ * doesNotContain('foo', ['bar']) // true
+ * ```
+ */
+export declare function doesNotContain(needle: string, haystack: string[]): boolean;

package/dist/helpers.d.ts

@@ -0,0 +1,174 @@
+import type { Arrayable, Nullable } from '@stacksjs/types';
+/**
+ * Convert `Arrayable<T>` to `Array<T>`
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * toArray('foo') // ['foo']
+ * toArray(['foo']) // ['foo']
+ * toArray(null) // []
+ * toArray(undefined) // []
+ * toArray(1) // [1]
+ * toArray([1]) // [1]
+ * toArray({ foo: 'bar' }) // [{ foo: 'bar' }]
+ * toArray([{ foo: 'bar' }]) // [{ foo: 'bar' }]
+ * ```
+ */
+export declare function toArray<T>(array?: Nullable<Arrayable<T>>): Array<T>;
+/**
+ * Flatten `Arrayable<T>` to `Array<T>`
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * flatten([1, [2, [3, [4, [5]]]]]) // [1, 2, 3, 4, 5]
+ * ```
+ */
+export declare function flatten<T>(array?: Nullable<Arrayable<T | Array<T>>>): Array<T>;
+/**
+ * Use rest arguments to merge arrays
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * mergeArrayable([1, 2], [3, 4], [5, 6]) // [1, 2, 3, 4, 5, 6]
+ * ```
+ */
+export declare function mergeArrayable<T>(...args: Nullable<Arrayable<T>>[]): Array<T>;
+export type PartitionFilter<T> = (i: T, idx: number, arr: readonly T[]) => any;
+/**
+ * Divide an array into two parts by a filter function
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * const [odd, even] = partition([1, 2, 3, 4], i => i % 2 != 0)
+ * console.log(odd) // [1, 3]
+ * console.log(even) // [2, 4]
+ * ```
+ */
+export declare function partition<T>(array: readonly T[], f1: PartitionFilter<T>): [T[], T[]];
+export declare function partition<T>(array: readonly T[], f1: PartitionFilter<T>, f2: PartitionFilter<T>): [T[], T[], T[]];
+export declare function partition<T>(array: readonly T[], f1: PartitionFilter<T>, f2: PartitionFilter<T>, f3: PartitionFilter<T>): [T[], T[], T[], T[]];
+export declare function partition<T>(array: readonly T[], f1: PartitionFilter<T>, f2: PartitionFilter<T>, f3: PartitionFilter<T>, f4: PartitionFilter<T>): [T[], T[], T[], T[], T[]];
+export declare function partition<T>(array: readonly T[], f1: PartitionFilter<T>, f2: PartitionFilter<T>, f3: PartitionFilter<T>, f4: PartitionFilter<T>, f5: PartitionFilter<T>): [T[], T[], T[], T[], T[], T[]];
+export declare function partition<T>(array: readonly T[], f1: PartitionFilter<T>, f2: PartitionFilter<T>, f3: PartitionFilter<T>, f4: PartitionFilter<T>, f5: PartitionFilter<T>, f6: PartitionFilter<T>): [T[], T[], T[], T[], T[], T[], T[]];
+/**
+ * Unique an Array
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * uniq([1, 2, 3, 3, 2, 1]) // [1, 2, 3]
+ * ```
+ */
+export declare function uniq<T>(array: readonly T[]): T[];
+/**
+ * Unique an Array
+ *
+ * @param array
+ * @example
+ * ```ts
+ * unique([1, 2, 3, 3, 2, 1]) // [1, 2, 3]
+ * ```
+ */
+export declare function unique<T>(array: readonly T[]): T[];
+/**
+ * Unique an Array by a custom equality function
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * uniqueBy([1, 2, 3, 3, 2, 1], (a, b) => a === b) // [1, 2, 3]
+ * ```
+ */
+export declare function uniqueBy<T>(array: readonly T[], equalFn: (a: any, b: any) => boolean): T[];
+/**
+ * Get last item
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * last([1, 2, 3]) // 3
+ * ```
+ */
+export declare function last(array: readonly []): undefined;
+export declare function last<T>(array: readonly T[]): T;
+/**
+ * Remove an item from Array
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * const arr = [1, 2, 3]
+ * remove(arr, 2) // true
+ * Arr.remove(arr, 4) // false
+ * console.log(arr) // [1, 3]
+ */
+export declare function remove<T>(array: T[], value: T): boolean;
+/**
+ * Get nth item of Array. Negative for backward
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * at([1, 2, 3], 1) // 2
+ * at([1, 2, 3], -1) // 3
+ * at([1, 2, 3], 3) // undefined
+ * at([1, 2, 3], -4) // undefined
+ * ```
+ */
+export declare function at(array: readonly [], index: number): undefined;
+export declare function at<T>(array: readonly T[], index: number): T;
+/**
+ * Move an item from one index to another
+ * @param array
+ * @param from
+ * @param to
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * move([1, 2, 3, 4], 0, 2) // [2, 3, 1, 4]
+ * move([1, 2, 3, 4], 0, -1) // [2, 3, 4, 1]
+ * move([1, 2, 3, 4], -1, 0) // [4, 1, 2, 3]
+ * move([1, 2, 3, 4], -1, -2) // [1, 4, 2, 3]
+ * move([1, 2, 3, 4], 1, 1) // [1, 2, 3, 4]
+ * ```
+ */
+export declare function move<T>(array: T[], from: number, to: number): T[];
+/**
+ * Clamp a number to the index range of an array.
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * clampArrayRange([1, 2, 3], 0) // 0
+ * clampArrayRange([1, 2, 3], 1) // 1
+ * clampArrayRange([1, 2, 3], 2) // 2
+ * clampArrayRange([1, 2, 3], 3) // 2
+ * clampArrayRange([1, 2, 3], 4) // 2
+ * clampArrayRange([1, 2, 3], -1) // 0
+ */
+export declare function clampArrayRange(arr: readonly unknown[], n: number): number;
+/**
+ * Get random items from an array
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * sample([1, 2, 3, 4], 2) // [2, 3]
+ * ```
+ */
+export declare function sample<T>(arr: T[], count: number): (T | undefined)[];
+/**
+ * Shuffle an array. This function mutates the array.
+ *
+ * @category Array
+ * @example
+ * ```ts
+ * shuffle([1, 2, 3, 4]) // [2, 4, 1, 3]
+ * ```
+ */
+export declare function shuffle<T>(array: T[]): T[];

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './arr';
+export * as arr from './arr';
+export * from './macro';

package/dist/macro.d.ts

@@ -0,0 +1,94 @@
+import type { Arrayable, Nullable } from '@stacksjs/types';
+import type { PartitionFilter } from './helpers';
+export declare const Arr: {
+    contains(needle: string, haystack: string[]): boolean;
+    containsAll(needles: string[], haystack: string[]): boolean;
+    containsAny(needles: string[], haystack: string[]): boolean;
+    containsNone(needles: string[], haystack: string[]): boolean;
+    containsOnly(needles: string[], haystack: string[]): boolean;
+    doesNotContain(needle: string, haystack: string[]): boolean;
+    toArray<T>(array?: Nullable<Arrayable<T>>): T[];
+    flatten<T_1>(array?: Nullable<Arrayable<T_1 | T_1[]>>): T_1[];
+    mergeArrayable<T_2>(...args: Nullable<Arrayable<T_2>>[]): T_2[];
+    partition<T_3>(array: readonly T_3[], filter: PartitionFilter<T_3>): [T_3[], T_3[]];
+    /**
+     * Returns a random item/s from the array
+     */
+    random<T_4>(arr: T_4[], count?: number): T_4[];
+    /**
+     * Returns random item/s from the array
+     */
+    sample<T_5>(arr: T_5[], count?: number): T_5[];
+    unique<T_6>(arr: T_6[]): T_6[];
+    uniqueBy<T_7>(arr: readonly T_7[], equalFn: (a: any, b: any) => boolean): T_7[];
+    last<T_8>(arr: T_8[]): T_8 | undefined;
+    remove<T_9>(arr: T_9[], value: T_9): boolean;
+    at(arr: any[], index: number): any;
+    range(arr: readonly number[]): number;
+    move<T_10>(arr: T_10[], from: number, to: number): T_10[];
+    clampArrayRange(arr: readonly unknown[], n: number): number;
+    shuffle<T_11>(arr: T_11[]): T_11[];
+    /**
+     * Returns the sum of all items in the array
+     */
+    sum(arr: number[]): number;
+    /**
+     * Returns the average of all items in the array
+     */
+    average(arr: number[]): number;
+    avg(arr: number[]): number;
+    /**
+     * Returns the median of all items in the array
+     */
+    median(arr: number[]): number;
+    /**
+     * Returns the mode of all items in the array
+     */
+    mode(arr: number[]): number;
+};
+export declare const arr: {
+    contains(needle: string, haystack: string[]): boolean;
+    containsAll(needles: string[], haystack: string[]): boolean;
+    containsAny(needles: string[], haystack: string[]): boolean;
+    containsNone(needles: string[], haystack: string[]): boolean;
+    containsOnly(needles: string[], haystack: string[]): boolean;
+    doesNotContain(needle: string, haystack: string[]): boolean;
+    toArray<T>(array?: Nullable<Arrayable<T>>): T[];
+    flatten<T_1>(array?: Nullable<Arrayable<T_1 | T_1[]>>): T_1[];
+    mergeArrayable<T_2>(...args: Nullable<Arrayable<T_2>>[]): T_2[];
+    partition<T_3>(array: readonly T_3[], filter: PartitionFilter<T_3>): [T_3[], T_3[]];
+    /**
+     * Returns a random item/s from the array
+     */
+    random<T_4>(arr: T_4[], count?: number): T_4[];
+    /**
+     * Returns random item/s from the array
+     */
+    sample<T_5>(arr: T_5[], count?: number): T_5[];
+    unique<T_6>(arr: T_6[]): T_6[];
+    uniqueBy<T_7>(arr: readonly T_7[], equalFn: (a: any, b: any) => boolean): T_7[];
+    last<T_8>(arr: T_8[]): T_8 | undefined;
+    remove<T_9>(arr: T_9[], value: T_9): boolean;
+    at(arr: any[], index: number): any;
+    range(arr: readonly number[]): number;
+    move<T_10>(arr: T_10[], from: number, to: number): T_10[];
+    clampArrayRange(arr: readonly unknown[], n: number): number;
+    shuffle<T_11>(arr: T_11[]): T_11[];
+    /**
+     * Returns the sum of all items in the array
+     */
+    sum(arr: number[]): number;
+    /**
+     * Returns the average of all items in the array
+     */
+    average(arr: number[]): number;
+    avg(arr: number[]): number;
+    /**
+     * Returns the median of all items in the array
+     */
+    median(arr: number[]): number;
+    /**
+     * Returns the mode of all items in the array
+     */
+    mode(arr: number[]): number;
+};

package/dist/math.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Returns the average of an array of numbers
+ * @param arr
+ * @category Array
+ * @example
+ * ```ts
+ * average([1, 2, 3, 4]) // 2.5
+ * ```
+ */
+export declare function average(arr: number[]): number;
+/**
+ * Returns the average of an array of numbers
+ * @param arr
+ * @category Array
+ * @example
+ * ```ts
+ * avg([1, 2, 3, 4]) // 2.5
+ * ```
+ */
+export declare function avg(arr: number[]): number;
+/**
+ * Returns the median of an array of numbers
+ * @param arr
+ * @category Array
+ * @example
+ * ```ts
+ * median([1, 2, 3, 4]) // 2.5
+ * ```
+ */
+export declare function median(arr: number[]): number;
+/**
+ * Returns the mode of an array of numbers
+ * @param arr
+ * @category Array
+ * @example
+ * ```ts
+ * mode([1, 2, 3, 4]) // 1
+ * mode([1, 2, 2, 3, 4]) // 2
+ * mode([1, 2, 2, 3, 3, 4]) // 2
+ * mode([1, 2, 2, 3, 3, 4, 4]) // 2
+ * mode([1, 2, 2, 3, 3, 4, 4, 4]) // 4
+ * ```
+ */
+export declare function mode(arr: number[]): number;
+/**
+ * Returns the sum of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * sum([1, 2, 3, 4]) // 10
+ * ```
+ */
+export declare function sum(array: readonly number[]): number;
+/**
+ * Returns the product of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * product([1, 2, 3, 4]) // 24
+ * ```
+ */
+export declare function product(array: readonly number[]): number;
+/**
+ * Returns the minimum value of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * min([1, 2, 3, 4]) // 1
+ * min([1, 2, 3, 4, -1]) // -1
+ * ```
+ */
+export declare function min(array: readonly number[]): number;
+/**
+ * Returns the maximum value of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * max([1, 2, 3, 4]) // 4
+ * max([1, 2, 3, 4, -1]) // 4
+ * ```
+ */
+export declare function max(array: readonly number[]): number;
+/**
+ * Returns the range of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * range([1, 2, 3, 4]) // 3
+ * range([1, 2, 3, 4, -1]) // 5
+ * range([1, 2, 3, 4, -1, 10]) // 11
+ * ```
+ */
+export declare function range(array: readonly number[]): number;
+/**
+ * Returns the variance of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * variance([1, 2, 3, 4]) // 1.25
+ * ```
+ * @see https://en.wikipedia.org/wiki/Variance
+ */
+export declare function variance(array: number[]): number;
+/**
+ * Returns the standard deviation of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * standardDeviation([1, 2, 3, 4]) // 1.118033988749895
+ * ```
+ * @see https://en.wikipedia.org/wiki/Standard_deviation
+ * @see https://stackoverflow.com/questions/7343890/standard-deviation-javascript
+ */
+export declare function standardDeviation(array: number[]): number;
+/**
+ * Returns the z-score of a number in an array of numbers
+ * @param array
+ * @param num
+ * @category Array
+ * @example
+ * ```ts
+ * zScore([1, 2, 3, 4], 2) // 0
+ * zScore([1, 2, 3, 4], 3) // 0.7071067811865475
+ * ```
+ * @see https://en.wikipedia.org/wiki/Standard_score
+ */
+export declare function zScore(array: number[], num: number): number;
+/**
+ * Returns the percentile of a number in an array of numbers
+ * @param array
+ * @param num
+ * @category Array
+ * @example
+ * ```ts
+ * percentile([1, 2, 3, 4], 2) // 0.25
+ * percentile([1, 2, 3, 4], 3) // 0.75
+ * ```
+ * @see https://en.wikipedia.org/wiki/Percentile
+ */
+export declare function percentile(array: number[], num: number): number;
+/**
+ * Returns the interquartile range of an array of numbers
+ * @param array
+ * @category Array
+ * @example
+ * ```ts
+ * interquartileRange([1, 2, 3, 4]) // 1.5
+ * ```
+ * @see https://en.wikipedia.org/wiki/Interquartile_range
+ * @see https://stackoverflow.com/questions/48719873/how-to-calculate-interquartile-range-in-javascript
+ */
+export declare function interquartileRange(array: number[]): number;
+/**
+ * Returns the covariance of two arrays of numbers
+ * @param array1
+ * @param array2
+ * @category Array
+ * @example
+ * ```ts
+ * covariance([1, 2, 3, 4], [1, 2, 3, 4]) // 1.25
+ * covariance([1, 2, 3, 4], [4, 3, 2, 1]) // -1.25
+ * ```
+ */
+export declare function covariance(array1: number[], array2: number[]): number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/arrays",
   "type": "module",
-  "version": "0.58.73",
+  "version": "0.59.2",
   "description": "The Stacks array utilities.",
   "author": "Chris Breuer",
   "license": "MIT",