@stacksjs/arrays 0.39.1 → 0.40.0

package/dist/index.d.ts

@@ -1,5 +1,97 @@
+import type { Arrayable, Nullable } from '@stacksjs/types';
 export declare function contains(needle: string, haystack: string[]): boolean;
 export declare function containsAll(needles: string[], haystack: string[]): boolean;
 export declare function containsAny(needles: string[], haystack: string[]): boolean;
 export declare function containsNone(needles: string[], haystack: string[]): boolean;
 export declare function containsOnly(needles: string[], haystack: string[]): boolean;
+/**
+ * Convert `Arrayable<T>` to `Array<T>`
+ *
+ * @category Array
+ */
+export declare function toArray<T>(array?: Nullable<Arrayable<T>>): Array<T>;
+/**
+ * Convert `Arrayable<T>` to `Array<T>` and flatten it
+ *
+ * @category Array
+ */
+export declare function flattenArrayable<T>(array?: Nullable<Arrayable<T | Array<T>>>): Array<T>;
+/**
+ * Use rest arguments to merge arrays
+ *
+ * @category Array
+ */
+export declare function mergeArrayable<T>(...args: Nullable<Arrayable<T>>[]): Array<T>;
+export declare type PartitionFilter<T> = (i: T, idx: number, arr: readonly T[]) => any;
+/**
+ * Divide an array into two parts by a filter function
+ *
+ * @category Array
+ * @example const [odd, even] = partition([1, 2, 3, 4], i => i % 2 != 0)
+ */
+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
+ */
+export declare function uniq<T>(array: readonly T[]): T[];
+/**
+ * Get last item
+ *
+ * @category Array
+ */
+export declare function last(array: readonly []): undefined;
+export declare function last<T>(array: readonly T[]): T;
+/**
+ * Remove an item from Array
+ *
+ * @category Array
+ */
+export declare function remove<T>(array: T[], value: T): boolean;
+/**
+ * Get nth item of Array. Negative for backward
+ *
+ * @category Array
+ */
+export declare function at(array: readonly [], index: number): undefined;
+export declare function at<T>(array: readonly T[], index: number): T;
+/**
+ * Generate a range array of numbers. The `stop` is exclusive.
+ *
+ * @category Array
+ */
+export declare function range(stop: number): number[];
+export declare function range(start: number, stop: number, step?: number): number[];
+/**
+ * Move element in an Array
+ *
+ * @category Array
+ * @param arr
+ * @param from
+ * @param to
+ */
+export declare function move<T>(arr: T[], from: number, to: number): T[];
+/**
+ * Clamp a number to the index range of an array.
+ *
+ * @category Array
+ */
+export declare function clampArrayRange(n: number, arr: readonly unknown[]): any;
+/**
+ * Get random items from an array
+ *
+ * @category Array
+ */
+export declare function sample<T>(arr: T[], count: number): T[];
+/**
+ * Shuffle an array. This function mutates the array.
+ *
+ * @category Array
+ */
+export declare function shuffle<T>(array: T[]): T[];

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { clamp } from "@stacksjs/utils";
 export function contains(needle, haystack) {
   return haystack.some((hay) => needle.includes(hay));
 }
@@ -13,3 +14,86 @@ export function containsNone(needles, haystack) {
 export function containsOnly(needles, haystack) {
   return containsAll(haystack, needles);
 }
+export function toArray(array) {
+  array = array ?? [];
+  return Array.isArray(array) ? array : [array];
+}
+export function flattenArrayable(array) {
+  return toArray(array).flat(1);
+}
+export function mergeArrayable(...args) {
+  return args.flatMap((i) => toArray(i));
+}
+export function partition(array, ...filters) {
+  const result = new Array(filters.length + 1).fill(null).map(() => []);
+  array.forEach((e, idx, arr) => {
+    let i = 0;
+    for (const filter of filters) {
+      if (filter(e, idx, arr)) {
+        result[i].push(e);
+        return;
+      }
+      i += 1;
+    }
+    result[i].push(e);
+  });
+  return result;
+}
+export function uniq(array) {
+  return Array.from(new Set(array));
+}
+export function last(array) {
+  return at(array, -1);
+}
+export function remove(array, value) {
+  if (!array)
+    return false;
+  const index = array.indexOf(value);
+  if (index >= 0) {
+    array.splice(index, 1);
+    return true;
+  }
+  return false;
+}
+export function at(array, index) {
+  const len = array.length;
+  if (!len)
+    return void 0;
+  if (index < 0)
+    index += len;
+  return array[index];
+}
+export function range(...args) {
+  let start, stop, step;
+  if (args.length === 1) {
+    start = 0;
+    step = 1;
+    [stop] = args;
+  } else {
+    [start, stop, step = 1] = args;
+  }
+  const arr = [];
+  let current = start;
+  while (current < stop) {
+    arr.push(current);
+    current += step || 1;
+  }
+  return arr;
+}
+export function move(arr, from, to) {
+  arr.splice(to, 0, arr.splice(from, 1)[0]);
+  return arr;
+}
+export function clampArrayRange(n, arr) {
+  return clamp(n, 0, arr.length - 1);
+}
+export function sample(arr, count) {
+  return Array.from({ length: count }, (_) => arr[Math.round(Math.random() * (arr.length - 1))]);
+}
+export function shuffle(array) {
+  for (let i = array.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [array[i], array[j]] = [array[j], array[i]];
+  }
+  return array;
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@stacksjs/arrays",
   "type": "module",
-  "version": "0.39.1",
-  "packageManager": "pnpm@7.15.0",
+  "version": "0.40.0",
+  "packageManager": "pnpm@7.16.0",
   "description": "The Stacks array utilities.",
   "author": "Chris Breuer",
   "license": "MIT",
@@ -36,7 +36,7 @@
   ],
   "engines": {
     "node": ">=v18.12.1",
-    "pnpm": ">=7.15.0"
+    "pnpm": ">=7.16.0"
   },
   "devDependencies": {
     "mkdist": "^0.4.0",