@zairakai/js-utils 1.0.0

package/dist/chunk-TY75OOIQ.js

@@ -0,0 +1,700 @@
+import {
+  isEqual
+} from "./chunk-LDSWHSRX.js";
+
+// src/collections.ts
+var EnhancedArray = class _EnhancedArray extends Array {
+  /**
+   * Create a new EnhancedArray instance.
+   *
+   * @param {...T[]} items The items to initialize the collection with
+   */
+  constructor(...items) {
+    super(...items);
+    Object.setPrototypeOf(this, _EnhancedArray.prototype);
+    this.originalItems = structuredClone(items);
+  }
+  /**
+   * Determine if the collection has been modified since initialization or last sync.
+   *
+   * @returns {boolean} True if modified, false otherwise
+   */
+  isDirty() {
+    return !isEqual(this.originalItems, Array.from(this));
+  }
+  /**
+   * Determine if the collection is clean (not modified).
+   *
+   * @returns {boolean} True if not modified, false otherwise
+   */
+  isClean() {
+    return !this.isDirty();
+  }
+  /**
+   * Sync the original items with current items to mark the collection as clean.
+   *
+   * @returns {this} The collection instance
+   */
+  syncOriginal() {
+    this.originalItems = structuredClone(Array.from(this));
+    return this;
+  }
+  /**
+   * Compare with another array or collection for equality.
+   *
+   * @param {T[] | EnhancedArray<T>} other The array or collection to compare with
+   * @returns {boolean} True if equivalent, false otherwise
+   */
+  isEquivalent(other) {
+    return isEqual(Array.from(this), Array.from(other));
+  }
+  /**
+   * Create an EnhancedArray from an iterable or array-like object.
+   *
+   * @param {Iterable<T> | ArrayLike<T>} items The items to convert
+   * @returns {EnhancedArray<T>} A new EnhancedArray instance
+   */
+  static from(items) {
+    return new _EnhancedArray(...Array.from(items));
+  }
+  /**
+   * Create an EnhancedArray from a variable number of arguments.
+   *
+   * @param {...T[]} items The items to include
+   * @returns {EnhancedArray<T>} A new EnhancedArray instance
+   */
+  static of(...items) {
+    return new _EnhancedArray(...items);
+  }
+  // Laravel Collection inspired methods
+  /**
+   * Create a new collection instance from the current items.
+   *
+   * @returns {EnhancedArray<T>} A new EnhancedArray instance
+   */
+  collect() {
+    return new _EnhancedArray(...this);
+  }
+  /**
+   * Pluck an array of values from an array of objects.
+   *
+   * @param {K} key The key to pluck
+   * @returns {EnhancedArray<T[K]>} A new collection of plucked values
+   */
+  pluck(key) {
+    return new _EnhancedArray(
+      ...this.map((item) => item && "object" === typeof item ? item[key] : void 0).filter(
+        (val) => val !== void 0
+      )
+    );
+  }
+  /**
+   * Group the collection's items by a given key or callback.
+   *
+   * @param {K | Callback<T, string | number>} key The key or callback to group by
+   * @returns {Record<string, EnhancedArray<T>>} A record of grouped collections
+   */
+  groupBy(key) {
+    const groups = {};
+    for (let i = 0; i < this.length; i++) {
+      const item = this[i];
+      const groupKey = "function" === typeof key ? String(key(item, i)) : String(item && "object" === typeof item ? item[key] : item);
+      if (!groups[groupKey]) {
+        groups[groupKey] = new _EnhancedArray();
+      }
+      groups[groupKey].push(item);
+    }
+    return groups;
+  }
+  /**
+   * Return only unique items from the collection.
+   *
+   * @param {K} [key] Optional key to determine uniqueness for objects
+   * @returns {EnhancedArray<T>} A new collection of unique items
+   */
+  unique(key) {
+    if (!key) {
+      return new _EnhancedArray(...new Set(this));
+    }
+    const seen = /* @__PURE__ */ new Set();
+    return new _EnhancedArray(
+      ...this.filter((item) => {
+        const value = item && "object" === typeof item ? item[key] : item;
+        if (seen.has(value)) {
+          return false;
+        }
+        seen.add(value);
+        return true;
+      })
+    );
+  }
+  /**
+   * Chunk the collection into smaller collections of a given size.
+   *
+   * @param {number} size The size of each chunk
+   * @returns {EnhancedArray<EnhancedArray<T>>} A collection of chunked collections
+   */
+  chunk(size) {
+    const chunks = new _EnhancedArray();
+    for (let i = 0; i < this.length; i += size) {
+      chunks.push(new _EnhancedArray(...this.slice(i, i + size)));
+    }
+    return chunks;
+  }
+  // Advanced manipulation methods
+  /**
+   * Flatten a multi-dimensional collection into a single level.
+   *
+   * @param {number} [depth=Infinity] The depth to flatten to
+   * @returns {EnhancedArray<unknown>} A new flattened collection
+   */
+  deepFlatten(depth = Infinity) {
+    const flatten = (arr, currentDepth) => {
+      const result = [];
+      for (const item of arr) {
+        if (Array.isArray(item) && 0 < currentDepth) {
+          result.push(...flatten(item, currentDepth - 1));
+        } else {
+          result.push(item);
+        }
+      }
+      return result;
+    };
+    return new _EnhancedArray(...flatten(this, depth));
+  }
+  /**
+   * Rotate the collection by a given number of positions.
+   *
+   * @param {number} [positions=1] The number of positions to rotate
+   * @returns {EnhancedArray<T>} A new rotated collection
+   */
+  rotate(positions = 1) {
+    if (0 === this.length) {
+      return new _EnhancedArray();
+    }
+    const count = this.length;
+    positions = positions % count;
+    if (0 === positions) {
+      return this.collect();
+    }
+    if (0 > positions) {
+      positions = count + positions;
+    }
+    return new _EnhancedArray(...this.slice(positions), ...this.slice(0, positions));
+  }
+  /**
+   * Chunk the collection as long as the given predicate returns true.
+   *
+   * @param {Predicate<T>} predicate The predicate to check
+   * @returns {EnhancedArray<EnhancedArray<T>>} A collection of chunked collections
+   */
+  chunkWhile(predicate) {
+    const chunks = new _EnhancedArray();
+    let currentChunk = new _EnhancedArray();
+    for (let i = 0; i < this.length; i++) {
+      const item = this[i];
+      if (0 < currentChunk.length && !predicate(item, i)) {
+        chunks.push(currentChunk);
+        currentChunk = new _EnhancedArray();
+      }
+      currentChunk.push(item);
+    }
+    if (0 < currentChunk.length) {
+      chunks.push(currentChunk);
+    }
+    return chunks;
+  }
+  /**
+   * Transpose the collection (swap rows and columns).
+   *
+   * @returns {EnhancedArray<EnhancedArray<unknown>>} A new transposed collection
+   */
+  transpose() {
+    if (0 === this.length) {
+      return new _EnhancedArray();
+    }
+    const maxLength = Math.max(...this.map((row) => Array.isArray(row) ? row.length : 1));
+    const result = new _EnhancedArray();
+    for (let i = 0; i < maxLength; i++) {
+      const column = new _EnhancedArray(
+        ...this.map((row) => {
+          if (Array.isArray(row)) {
+            return row[i] ?? null;
+          }
+          return 0 === i ? row : null;
+        })
+      );
+      result.push(column);
+    }
+    return result;
+  }
+  // Validation methods
+  /**
+   * Check if the collection is sorted.
+   *
+   * @param {Function} [compareFn] Optional comparison function
+   * @returns {boolean} True if sorted, false otherwise
+   */
+  isSorted(compareFn) {
+    if (1 >= this.length) {
+      return true;
+    }
+    for (let i = 1; i < this.length; i++) {
+      const prev = this[i - 1];
+      const current = this[i];
+      if (compareFn) {
+        if (0 < compareFn(prev, current)) {
+          return false;
+        }
+      } else {
+        if (prev > current) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  /**
+   * Check if the collection contains duplicate items.
+   *
+   * @param {K} [key] Optional key to check for uniqueness in objects
+   * @returns {boolean} True if duplicates found, false otherwise
+   */
+  hasDuplicates(key) {
+    if (key) {
+      const seen = /* @__PURE__ */ new Set();
+      for (const item of this) {
+        const value = item && "object" === typeof item ? item[key] : item;
+        if (seen.has(value)) {
+          return true;
+        }
+        seen.add(value);
+      }
+      return false;
+    }
+    return this.length !== new Set(this).size;
+  }
+  // Statistical methods
+  /**
+   * Calculate the median value of the collection.
+   *
+   * @param {Callback<T, number>} [accessor] Optional accessor for non-numeric items
+   * @returns {number | null} The median value or null if collection is empty
+   */
+  median(accessor) {
+    if (0 === this.length) {
+      return null;
+    }
+    const values = accessor ? this.map(accessor) : this;
+    const sorted = [...values].sort((a, b) => a - b);
+    const count = sorted.length;
+    if (0 === count % 2) {
+      return (sorted[count / 2 - 1] + sorted[count / 2]) / 2;
+    }
+    return sorted[Math.floor(count / 2)];
+  }
+  /**
+   * Calculate the mode (most frequent values) of the collection.
+   *
+   * @param {Callback<T, unknown>} [accessor] Optional accessor for the values
+   * @returns {EnhancedArray<unknown>} A collection of mode values
+   */
+  mode(accessor) {
+    if (0 === this.length) {
+      return new _EnhancedArray();
+    }
+    const frequencies = this.frequencies(accessor);
+    const maxFrequency = Math.max(...Object.values(frequencies));
+    return new _EnhancedArray(...Object.keys(frequencies).filter((key) => frequencies[key] === maxFrequency));
+  }
+  /**
+   * Calculate the standard deviation of the collection.
+   *
+   * @param {Callback<T, number>} [accessor] Optional accessor for non-numeric items
+   * @returns {number} The standard deviation
+   */
+  standardDeviation(accessor) {
+    if (0 === this.length) {
+      return 0;
+    }
+    const values = accessor ? this.map(accessor) : this;
+    const mean = values.reduce((sum, val) => sum + val, 0) / values.length;
+    const sumSquaredDifferences = values.reduce(
+      (sum, val) => sum + Math.pow(val - mean, 2),
+      0
+    );
+    return Math.sqrt(sumSquaredDifferences / values.length);
+  }
+  /**
+   * Calculate a specific percentile of the collection.
+   *
+   * @param {number} percentile The percentile to calculate (0-100)
+   * @param {Callback<T, number>} [accessor] Optional accessor for non-numeric items
+   * @returns {number | null} The percentile value or null if collection is empty
+   */
+  percentile(percentile, accessor) {
+    if (0 === this.length) {
+      return null;
+    }
+    const values = accessor ? this.map(accessor) : this;
+    const sorted = [...values].sort((a, b) => a - b);
+    const index = percentile / 100 * (sorted.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    if (lower === upper) {
+      return sorted[lower];
+    }
+    const weight = index - lower;
+    return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+  }
+  /**
+   * Calculate the frequencies of items in the collection.
+   *
+   * @param {Callback<T, unknown>} [accessor] Optional accessor for the values
+   * @returns {Record<string, number>} A record of values and their frequencies
+   */
+  frequencies(accessor) {
+    const frequencies = {};
+    for (let i = 0; i < this.length; i++) {
+      const item = this[i];
+      const key = accessor ? String(accessor(item, i)) : String(item);
+      frequencies[key] = (frequencies[key] || 0) + 1;
+    }
+    return frequencies;
+  }
+  // Advanced operations
+  /**
+   * Calculate the Cartesian product of the collection and other arrays.
+   *
+   * @param {...U[][]} arrays The arrays to calculate the product with
+   * @returns {EnhancedArray<[T, ...U[]]>} A collection of product combinations
+   */
+  cartesian(...arrays) {
+    const result = new _EnhancedArray();
+    const allArrays = [this, ...arrays];
+    function* cartesianProduct(arrays2, index = 0, current = []) {
+      if (index === arrays2.length) {
+        yield [...current];
+        return;
+      }
+      for (const item of arrays2[index]) {
+        yield* cartesianProduct(arrays2, index + 1, [...current, item]);
+      }
+    }
+    for (const combination of cartesianProduct(allArrays)) {
+      result.push(combination);
+    }
+    return result;
+  }
+  /**
+   * Interleave the collection with other arrays.
+   *
+   * @param {...U[][]} arrays The arrays to interleave with
+   * @returns {EnhancedArray<T | U>} A new interleaved collection
+   */
+  interleave(...arrays) {
+    const result = new _EnhancedArray();
+    const allArrays = [this, ...arrays];
+    const maxLength = Math.max(...allArrays.map((arr) => arr.length));
+    for (let i = 0; i < maxLength; i++) {
+      for (const array of allArrays) {
+        if (i < array.length) {
+          result.push(array[i]);
+        }
+      }
+    }
+    return result;
+  }
+  /**
+   * Get a sliding window of items from the collection.
+   *
+   * @param {number} [size=2] The size of the window
+   * @param {number} [step=1] The step between windows
+   * @returns {EnhancedArray<EnhancedArray<T>>} A collection of window collections
+   */
+  sliding(size = 2, step = 1) {
+    if (0 >= size || 0 >= step) {
+      return new _EnhancedArray();
+    }
+    const windows = new _EnhancedArray();
+    for (let i = 0; i <= this.length - size; i += step) {
+      windows.push(new _EnhancedArray(...this.slice(i, i + size)));
+    }
+    return windows;
+  }
+  // Navigation macros
+  /**
+   * Get the item at the given index.
+   *
+   * @param {number} index The index to retrieve
+   * @returns {T | undefined} The item at the index or undefined
+   */
+  at(index) {
+    return this[index];
+  }
+  /**
+   * Get the item before the given item.
+   *
+   * @param {T} item The item to search for
+   * @returns {T | undefined} The item before or undefined
+   */
+  before(item) {
+    const index = this.indexOf(item);
+    return 0 < index ? this[index - 1] : void 0;
+  }
+  /**
+   * Get the item after the given item.
+   *
+   * @param {T} item The item to search for
+   * @returns {T | undefined} The item after or undefined
+   */
+  after(item) {
+    const index = this.indexOf(item);
+    return 0 <= index && index < this.length - 1 ? this[index + 1] : void 0;
+  }
+  // Transformation macros
+  /**
+   * Chunk the collection by a given key or callback when its value changes.
+   *
+   * @param {K | Callback<T, unknown>} key The key or callback to chunk by
+   * @returns {EnhancedArray<EnhancedArray<T>>} A collection of chunked collections
+   */
+  chunkBy(key) {
+    if (0 === this.length) {
+      return new _EnhancedArray();
+    }
+    const chunks = new _EnhancedArray();
+    let currentChunk = new _EnhancedArray();
+    let lastValue = null;
+    for (let i = 0; i < this.length; i++) {
+      const item = this[i];
+      const currentValue = "function" === typeof key ? key(item, i) : item && "object" === typeof item ? item[key] : item;
+      if (0 === i || currentValue === lastValue) {
+        currentChunk.push(item);
+      } else {
+        chunks.push(currentChunk);
+        currentChunk = new _EnhancedArray(item);
+      }
+      lastValue = currentValue;
+    }
+    if (0 < currentChunk.length) {
+      chunks.push(currentChunk);
+    }
+    return chunks;
+  }
+  /**
+   * Map and filter the collection simultaneously.
+   * Items for which the callback returns null or undefined are removed.
+   *
+   * @param {Function} callback The callback to map items
+   * @returns {EnhancedArray<U>} A new mapped and filtered collection
+   */
+  filterMap(callback) {
+    const result = new _EnhancedArray();
+    for (let i = 0; i < this.length; i++) {
+      const mapped = callback(this[i], i);
+      if (null !== mapped && mapped !== void 0) {
+        result.push(mapped);
+      }
+    }
+    return result;
+  }
+  /**
+   * Extract a subset of properties from each item in the collection.
+   *
+   * @param {K[]} keys The keys to extract
+   * @returns {EnhancedArray<Partial<T>>} A new collection of partial items
+   */
+  extract(keys) {
+    return new _EnhancedArray(
+      ...this.map((item) => {
+        if (!item || "object" !== typeof item) {
+          return {};
+        }
+        const extracted = {};
+        for (const key of keys) {
+          if (key in item) {
+            extracted[key] = item[key];
+          }
+        }
+        return extracted;
+      })
+    );
+  }
+  // Utility macros
+  /**
+   * Get the first item or push a default item if the collection is empty.
+   *
+   * @param {T} item The default item to push if empty
+   * @returns {T} The first item or the pushed item
+   */
+  firstOrPush(item) {
+    if (0 === this.length) {
+      this.push(item);
+      return item;
+    }
+    return this[0];
+  }
+  /**
+   * Get every n-th item from the collection.
+   *
+   * @param {number} n The step size
+   * @returns {EnhancedArray<T>} A new collection of every n-th item
+   */
+  getNth(n) {
+    const result = new _EnhancedArray();
+    for (let i = n - 1; i < this.length; i += n) {
+      result.push(this[i]);
+    }
+    return result;
+  }
+  /**
+   * Get a random item from the collection based on weights.
+   *
+   * @param {number[]} [weights] Optional weights for each item
+   * @returns {T | undefined} A random item or undefined if collection is empty
+   */
+  weightedRandom(weights) {
+    if (0 === this.length) {
+      return void 0;
+    }
+    const effectiveWeights = weights ?? new Array(this.length).fill(1);
+    if (effectiveWeights.length !== this.length) {
+      throw new Error("Weights array must have same length as collection");
+    }
+    const totalWeight = effectiveWeights.reduce((sum, weight) => sum + weight, 0);
+    const random = Math.random() * totalWeight;
+    let currentWeight = 0;
+    for (let i = 0; i < this.length; i++) {
+      currentWeight += effectiveWeights[i];
+      if (random <= currentWeight) {
+        return this[i];
+      }
+    }
+    return this[this.length - 1];
+  }
+  /**
+   * Paginate the collection items.
+   *
+   * @param {number} perPage Items per page
+   * @param {number} [page=1] Current page number
+   * @returns {Object} Pagination results
+   */
+  paginate(perPage, page = 1) {
+    const total = this.length;
+    const lastPage = Math.ceil(total / perPage);
+    const currentPage = Math.max(1, Math.min(page, lastPage));
+    const from = (currentPage - 1) * perPage;
+    const to = Math.min(from + perPage, total);
+    return {
+      data: new _EnhancedArray(...this.slice(from, to)),
+      total,
+      perPage,
+      currentPage,
+      lastPage,
+      from: from + 1,
+      to
+    };
+  }
+  /**
+   * Recursively convert all nested arrays to EnhancedArray instances.
+   *
+   * @returns {EnhancedArray<unknown>} A new collection with recursive EnhancedArrays
+   */
+  recursive() {
+    const convert = (item) => {
+      if (Array.isArray(item)) {
+        return new _EnhancedArray(...item.map(convert));
+      }
+      if (item && "object" === typeof item && item.constructor === Object) {
+        const converted = {};
+        for (const [key, value] of Object.entries(item)) {
+          converted[key] = convert(value);
+        }
+        return converted;
+      }
+      return item;
+    };
+    return new _EnhancedArray(...this.map(convert));
+  }
+};
+var objectToMap = (obj) => {
+  return new Map(Object.entries(obj));
+};
+var mapToObject = (map) => {
+  return Object.fromEntries(map);
+};
+var EnhancedMap = class _EnhancedMap extends Map {
+  /**
+   * Create an EnhancedMap from a plain object.
+   *
+   * @param {Record<string, V>} obj The object to convert
+   * @returns {EnhancedMap<string, V>} A new EnhancedMap instance
+   */
+  static fromObject(obj) {
+    return new _EnhancedMap(Object.entries(obj));
+  }
+  /**
+   * Pluck a property from each value in the map.
+   *
+   * @param {P} key The key to pluck
+   * @returns {EnhancedArray<V[P]>} A new collection of plucked values
+   */
+  pluck(key) {
+    return new EnhancedArray(
+      ...Array.from(this.values()).map((value) => value && "object" === typeof value ? value[key] : void 0).filter((val) => val !== void 0)
+    );
+  }
+  /**
+   * Group the map's entries by a given accessor.
+   *
+   * @param {Function} accessor The accessor to group by
+   * @returns {Record<string, EnhancedArray<[K, V]>>} A record of grouped entries
+   */
+  groupBy(accessor) {
+    const groups = {};
+    for (const [key, value] of this) {
+      const groupKey = String(accessor(value, key));
+      if (!groups[groupKey]) {
+        groups[groupKey] = new EnhancedArray();
+      }
+      groups[groupKey].push([key, value]);
+    }
+    return groups;
+  }
+  /**
+   * Convert the map to an array of entries.
+   *
+   * @returns {EnhancedArray<[K, V]>} A collection of entries
+   */
+  toArray() {
+    return new EnhancedArray(...this.entries());
+  }
+  /**
+   * Convert the map to a plain object.
+   *
+   * @returns {Record<string, V>} A plain object representation of the map
+   */
+  toObject() {
+    const obj = {};
+    for (const [key, value] of this) {
+      obj[String(key)] = value;
+    }
+    return obj;
+  }
+};
+var collect = (items) => {
+  return new EnhancedArray(...items);
+};
+var collectMap = (entries) => {
+  return new EnhancedMap(entries);
+};
+
+export {
+  EnhancedArray,
+  objectToMap,
+  mapToObject,
+  EnhancedMap,
+  collect,
+  collectMap
+};