voltjs-framework 1.0.0

package/src/utils/collection.js

@@ -0,0 +1,772 @@
+/**
+ * VoltJS Collection Utilities (Lodash Alternative)
+ * 
+ * All the array, object, and function utilities you need — zero dependencies.
+ * Covers: chunk, debounce, throttle, cloneDeep, merge, pick, omit, get, set,
+ * groupBy, keyBy, uniq, flatten, intersection, difference, range, memoize, etc.
+ * 
+ * @example
+ * const { _ } = require('voltjs');
+ * 
+ * _.chunk([1,2,3,4,5], 2);           // [[1,2],[3,4],[5]]
+ * _.groupBy(users, 'role');            // { admin: [...], user: [...] }
+ * _.pick(obj, ['name', 'email']);      // { name: 'John', email: '...' }
+ * _.debounce(fn, 300);                // Debounced function
+ * _.cloneDeep(obj);                   // Deep clone
+ * _.get(obj, 'a.b.c', 'default');     // Deep path access
+ * _.classNames('btn', { active: true }); // 'btn active'
+ */
+
+'use strict';
+
+const _ = {
+
+  // ==========================================
+  // ARRAY UTILITIES
+  // ==========================================
+
+  /** Split array into chunks of `size` */
+  chunk(arr, size = 1) {
+    const result = [];
+    for (let i = 0; i < arr.length; i += size) {
+      result.push(arr.slice(i, i + size));
+    }
+    return result;
+  },
+
+  /** Remove falsy values (false, null, 0, '', undefined, NaN) */
+  compact(arr) {
+    return arr.filter(Boolean);
+  },
+
+  /** Flatten one level */
+  flatten(arr) {
+    return arr.reduce((acc, val) => acc.concat(val), []);
+  },
+
+  /** Flatten deeply (all nested levels) */
+  flattenDeep(arr) {
+    return arr.reduce((acc, val) =>
+      Array.isArray(val) ? acc.concat(_.flattenDeep(val)) : acc.concat(val), []);
+  },
+
+  /** Flatten to a specific depth */
+  flattenDepth(arr, depth = 1) {
+    if (depth <= 0) return arr.slice();
+    return arr.reduce((acc, val) =>
+      Array.isArray(val)
+        ? acc.concat(_.flattenDepth(val, depth - 1))
+        : acc.concat(val), []);
+  },
+
+  /** Unique values */
+  uniq(arr) {
+    return [...new Set(arr)];
+  },
+
+  /** Unique by iteratee function or property name */
+  uniqBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    const seen = new Set();
+    return arr.filter(item => {
+      const key = fn(item);
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  },
+
+  /** Intersection of arrays (common elements) */
+  intersection(...arrays) {
+    if (arrays.length === 0) return [];
+    const sets = arrays.slice(1).map(a => new Set(a));
+    return arrays[0].filter(item => sets.every(s => s.has(item)));
+  },
+
+  /** Difference: elements in first array not in others */
+  difference(arr, ...others) {
+    const otherSet = new Set(others.flat());
+    return arr.filter(item => !otherSet.has(item));
+  },
+
+  /** Union of arrays (unique combined) */
+  union(...arrays) {
+    return [...new Set(arrays.flat())];
+  },
+
+  /** Zip arrays together */
+  zip(...arrays) {
+    const maxLen = Math.max(...arrays.map(a => a.length));
+    const result = [];
+    for (let i = 0; i < maxLen; i++) {
+      result.push(arrays.map(a => a[i]));
+    }
+    return result;
+  },
+
+  /** Unzip: opposite of zip */
+  unzip(arr) {
+    if (arr.length === 0) return [];
+    return arr[0].map((_, i) => arr.map(row => row[i]));
+  },
+
+  /** Group by key or function */
+  groupBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    const result = {};
+    for (const item of arr) {
+      const key = fn(item);
+      if (!result[key]) result[key] = [];
+      result[key].push(item);
+    }
+    return result;
+  },
+
+  /** Index by key (one item per key) */
+  keyBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    const result = {};
+    for (const item of arr) {
+      result[fn(item)] = item;
+    }
+    return result;
+  },
+
+  /** Sort by key or function (stable, returns new array) */
+  sortBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    return [...arr].sort((a, b) => {
+      const va = fn(a);
+      const vb = fn(b);
+      if (va < vb) return -1;
+      if (va > vb) return 1;
+      return 0;
+    });
+  },
+
+  /** Order by multiple keys (with direction) */
+  orderBy(arr, keys, orders = []) {
+    return [...arr].sort((a, b) => {
+      for (let i = 0; i < keys.length; i++) {
+        const key = keys[i];
+        const order = (orders[i] || 'asc') === 'desc' ? -1 : 1;
+        const va = typeof key === 'function' ? key(a) : a[key];
+        const vb = typeof key === 'function' ? key(b) : b[key];
+        if (va < vb) return -1 * order;
+        if (va > vb) return 1 * order;
+      }
+      return 0;
+    });
+  },
+
+  /** Count occurrences by key or function */
+  countBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    const result = {};
+    for (const item of arr) {
+      const key = fn(item);
+      result[key] = (result[key] || 0) + 1;
+    }
+    return result;
+  },
+
+  /** Partition array into two: [truthy, falsy] */
+  partition(arr, predicate) {
+    const truthy = [];
+    const falsy = [];
+    for (const item of arr) {
+      (predicate(item) ? truthy : falsy).push(item);
+    }
+    return [truthy, falsy];
+  },
+
+  /** Sample: random element */
+  sample(arr) {
+    return arr[Math.floor(Math.random() * arr.length)];
+  },
+
+  /** Sample N random elements */
+  sampleSize(arr, n = 1) {
+    const shuffled = _.shuffle(arr);
+    return shuffled.slice(0, n);
+  },
+
+  /** Shuffle array (Fisher-Yates) */
+  shuffle(arr) {
+    const result = [...arr];
+    for (let i = result.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+  },
+
+  /** First N elements */
+  take(arr, n = 1) {
+    return arr.slice(0, n);
+  },
+
+  /** Last N elements */
+  takeLast(arr, n = 1) {
+    return arr.slice(-n);
+  },
+
+  /** Drop first N elements */
+  drop(arr, n = 1) {
+    return arr.slice(n);
+  },
+
+  /** Drop last N elements */
+  dropLast(arr, n = 1) {
+    return arr.slice(0, -n || undefined);
+  },
+
+  /** First element */
+  first(arr) {
+    return arr[0];
+  },
+
+  /** Last element */
+  last(arr) {
+    return arr[arr.length - 1];
+  },
+
+  /** Find the min value in array (by iteratee) */
+  minBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    return arr.reduce((min, item) => fn(item) < fn(min) ? item : min);
+  },
+
+  /** Find the max value in array (by iteratee) */
+  maxBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    return arr.reduce((max, item) => fn(item) > fn(max) ? item : max);
+  },
+
+  /** Sum of values */
+  sum(arr) {
+    return arr.reduce((s, v) => s + v, 0);
+  },
+
+  /** Sum by key or function */
+  sumBy(arr, iteratee) {
+    const fn = typeof iteratee === 'function' ? iteratee : (item) => item[iteratee];
+    return arr.reduce((s, item) => s + fn(item), 0);
+  },
+
+  /** Mean (average) */
+  mean(arr) {
+    return arr.length === 0 ? 0 : _.sum(arr) / arr.length;
+  },
+
+  /** Generate a range of numbers */
+  range(start, end, step = 1) {
+    if (end === undefined) { end = start; start = 0; }
+    const result = [];
+    if (step > 0) {
+      for (let i = start; i < end; i += step) result.push(i);
+    } else if (step < 0) {
+      for (let i = start; i > end; i += step) result.push(i);
+    }
+    return result;
+  },
+
+  /** Create an array of N items, each filled by fn */
+  times(n, fn) {
+    return Array.from({ length: n }, (_, i) => fn(i));
+  },
+
+  // ==========================================
+  // OBJECT UTILITIES
+  // ==========================================
+
+  /** Deep get by path string: _.get(obj, 'a.b[0].c', default) */
+  get(obj, path, defaultValue = undefined) {
+    const keys = String(path).replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+    let result = obj;
+    for (const key of keys) {
+      if (result === null || result === undefined) return defaultValue;
+      result = result[key];
+    }
+    return result === undefined ? defaultValue : result;
+  },
+
+  /** Deep set by path string: _.set(obj, 'a.b.c', value) */
+  set(obj, path, value) {
+    const keys = String(path).replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+    let curr = obj;
+    for (let i = 0; i < keys.length - 1; i++) {
+      const key = keys[i];
+      const nextKey = keys[i + 1];
+      if (curr[key] === undefined || curr[key] === null) {
+        curr[key] = /^\d+$/.test(nextKey) ? [] : {};
+      }
+      curr = curr[key];
+    }
+    curr[keys[keys.length - 1]] = value;
+    return obj;
+  },
+
+  /** Check if path exists */
+  has(obj, path) {
+    const keys = String(path).replace(/\[(\d+)\]/g, '.$1').split('.').filter(Boolean);
+    let curr = obj;
+    for (const key of keys) {
+      if (curr === undefined || curr === null || !Object.prototype.hasOwnProperty.call(curr, key)) {
+        return false;
+      }
+      curr = curr[key];
+    }
+    return true;
+  },
+
+  /** Pick specific keys from object */
+  pick(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+      if (key in obj) result[key] = obj[key];
+    }
+    return result;
+  },
+
+  /** Omit specific keys from object */
+  omit(obj, keys) {
+    const keySet = new Set(keys);
+    const result = {};
+    for (const key of Object.keys(obj)) {
+      if (!keySet.has(key)) result[key] = obj[key];
+    }
+    return result;
+  },
+
+  /** Pick by predicate function */
+  pickBy(obj, predicate) {
+    const result = {};
+    for (const [key, val] of Object.entries(obj)) {
+      if (predicate(val, key)) result[key] = val;
+    }
+    return result;
+  },
+
+  /** Omit by predicate function */
+  omitBy(obj, predicate) {
+    return _.pickBy(obj, (val, key) => !predicate(val, key));
+  },
+
+  /** Map object values */
+  mapValues(obj, fn) {
+    const result = {};
+    for (const [key, val] of Object.entries(obj)) {
+      result[key] = fn(val, key);
+    }
+    return result;
+  },
+
+  /** Map object keys */
+  mapKeys(obj, fn) {
+    const result = {};
+    for (const [key, val] of Object.entries(obj)) {
+      result[fn(key, val)] = val;
+    }
+    return result;
+  },
+
+  /** Invert keys and values */
+  invert(obj) {
+    const result = {};
+    for (const [key, val] of Object.entries(obj)) {
+      result[val] = key;
+    }
+    return result;
+  },
+
+  /** Deep merge (objects are merged, arrays replaced) */
+  merge(...objects) {
+    const result = {};
+    for (const obj of objects) {
+      for (const [key, val] of Object.entries(obj)) {
+        if (val && typeof val === 'object' && !Array.isArray(val) &&
+            result[key] && typeof result[key] === 'object' && !Array.isArray(result[key])) {
+          result[key] = _.merge(result[key], val);
+        } else {
+          result[key] = val;
+        }
+      }
+    }
+    return result;
+  },
+
+  /** Deep clone (handles nested objects, arrays, dates, regexps) */
+  cloneDeep(value) {
+    if (value === null || typeof value !== 'object') return value;
+    if (value instanceof Date) return new Date(value.getTime());
+    if (value instanceof RegExp) return new RegExp(value.source, value.flags);
+    if (value instanceof Map) {
+      const map = new Map();
+      for (const [k, v] of value) map.set(_.cloneDeep(k), _.cloneDeep(v));
+      return map;
+    }
+    if (value instanceof Set) {
+      const set = new Set();
+      for (const v of value) set.add(_.cloneDeep(v));
+      return set;
+    }
+    if (Array.isArray(value)) return value.map(v => _.cloneDeep(v));
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = _.cloneDeep(v);
+    }
+    return result;
+  },
+
+  /** Shallow clone */
+  clone(value) {
+    if (Array.isArray(value)) return [...value];
+    if (value && typeof value === 'object') return { ...value };
+    return value;
+  },
+
+  /** Deep equality check */
+  isEqual(a, b) {
+    if (a === b) return true;
+    if (a === null || b === null || typeof a !== typeof b) return false;
+    if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+    if (a instanceof RegExp && b instanceof RegExp) return a.toString() === b.toString();
+    if (typeof a !== 'object') return false;
+
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+
+    return keysA.every(key => _.isEqual(a[key], b[key]));
+  },
+
+  /** Check if value is empty ([], {}, '', null, undefined) */
+  isEmpty(value) {
+    if (value === null || value === undefined) return true;
+    if (typeof value === 'string' || Array.isArray(value)) return value.length === 0;
+    if (value instanceof Map || value instanceof Set) return value.size === 0;
+    if (typeof value === 'object') return Object.keys(value).length === 0;
+    return false;
+  },
+
+  /** Freeze deeply (immutable) */
+  freezeDeep(obj) {
+    Object.freeze(obj);
+    for (const val of Object.values(obj)) {
+      if (val && typeof val === 'object' && !Object.isFrozen(val)) {
+        _.freezeDeep(val);
+      }
+    }
+    return obj;
+  },
+
+  /** Convert entries to object */
+  fromEntries(entries) {
+    return Object.fromEntries(entries);
+  },
+
+  // ==========================================
+  // FUNCTION UTILITIES
+  // ==========================================
+
+  /** Debounce: delay fn execution until N ms after last call */
+  debounce(fn, wait = 300, options = {}) {
+    let timer = null;
+    let lastArgs = null;
+    let lastResult;
+    const leading = options.leading || false;
+    const trailing = options.trailing !== false;
+
+    function debounced(...args) {
+      lastArgs = args;
+      const callNow = leading && !timer;
+
+      if (timer) clearTimeout(timer);
+
+      timer = setTimeout(() => {
+        timer = null;
+        if (trailing && lastArgs) {
+          lastResult = fn.apply(this, lastArgs);
+          lastArgs = null;
+        }
+      }, wait);
+
+      if (callNow) {
+        lastResult = fn.apply(this, args);
+      }
+
+      return lastResult;
+    }
+
+    debounced.cancel = () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      lastArgs = null;
+    };
+
+    debounced.flush = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+        if (lastArgs) {
+          lastResult = fn.apply(undefined, lastArgs);
+          lastArgs = null;
+        }
+      }
+      return lastResult;
+    };
+
+    return debounced;
+  },
+
+  /** Throttle: limit fn to at most once per N ms */
+  throttle(fn, wait = 300, options = {}) {
+    let timer = null;
+    let lastCall = 0;
+    let lastResult;
+    const leading = options.leading !== false;
+    const trailing = options.trailing !== false;
+
+    function throttled(...args) {
+      const now = Date.now();
+
+      if (!lastCall && !leading) lastCall = now;
+
+      const remaining = wait - (now - lastCall);
+
+      if (remaining <= 0) {
+        if (timer) { clearTimeout(timer); timer = null; }
+        lastCall = now;
+        lastResult = fn.apply(this, args);
+      } else if (!timer && trailing) {
+        timer = setTimeout(() => {
+          lastCall = leading ? Date.now() : 0;
+          timer = null;
+          lastResult = fn.apply(this, args);
+        }, remaining);
+      }
+
+      return lastResult;
+    }
+
+    throttled.cancel = () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      lastCall = 0;
+    };
+
+    return throttled;
+  },
+
+  /** Execute function only once */
+  once(fn) {
+    let called = false;
+    let result;
+    return function (...args) {
+      if (!called) {
+        called = true;
+        result = fn.apply(this, args);
+      }
+      return result;
+    };
+  },
+
+  /** Memoize function results */
+  memoize(fn, resolver) {
+    const cache = new Map();
+    const memoized = function (...args) {
+      const key = resolver ? resolver(...args) : args[0];
+      if (cache.has(key)) return cache.get(key);
+      const result = fn.apply(this, args);
+      cache.set(key, result);
+      return result;
+    };
+    memoized.cache = cache;
+    memoized.clear = () => cache.clear();
+    return memoized;
+  },
+
+  /** Execute fn after N calls */
+  after(n, fn) {
+    let count = 0;
+    return function (...args) {
+      count++;
+      if (count >= n) return fn.apply(this, args);
+    };
+  },
+
+  /** Execute fn at most N times */
+  before(n, fn) {
+    let count = 0;
+    let result;
+    return function (...args) {
+      count++;
+      if (count < n) result = fn.apply(this, args);
+      return result;
+    };
+  },
+
+  /** Negate a predicate function */
+  negate(fn) {
+    return (...args) => !fn(...args);
+  },
+
+  /** Compose functions (right to left) */
+  compose(...fns) {
+    return (input) => fns.reduceRight((acc, fn) => fn(acc), input);
+  },
+
+  /** Pipe functions (left to right) */
+  pipe(...fns) {
+    return (input) => fns.reduce((acc, fn) => fn(acc), input);
+  },
+
+  /** Curry a function */
+  curry(fn) {
+    const arity = fn.length;
+    return function curried(...args) {
+      if (args.length >= arity) return fn(...args);
+      return (...moreArgs) => curried(...args, ...moreArgs);
+    };
+  },
+
+  /** Delay execution by ms */
+  delay(fn, ms, ...args) {
+    return new Promise(resolve => {
+      setTimeout(() => resolve(fn(...args)), ms);
+    });
+  },
+
+  /** Retry a function with exponential backoff */
+  async retry(fn, options = {}) {
+    const { attempts = 3, delay: d = 1000, backoff = 2 } = options;
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+      try {
+        return await fn(i);
+      } catch (err) {
+        lastErr = err;
+        if (i < attempts - 1) {
+          await new Promise(r => setTimeout(r, d * Math.pow(backoff, i)));
+        }
+      }
+    }
+    throw lastErr;
+  },
+
+  // ==========================================
+  // TYPE CHECKS
+  // ==========================================
+
+  isString(v) { return typeof v === 'string'; },
+  isNumber(v) { return typeof v === 'number' && !isNaN(v); },
+  isBoolean(v) { return typeof v === 'boolean'; },
+  isArray(v) { return Array.isArray(v); },
+  isObject(v) { return v !== null && typeof v === 'object' && !Array.isArray(v); },
+  isFunction(v) { return typeof v === 'function'; },
+  isNull(v) { return v === null; },
+  isUndefined(v) { return v === undefined; },
+  isNil(v) { return v === null || v === undefined; },
+  isDate(v) { return v instanceof Date && !isNaN(v); },
+  isRegExp(v) { return v instanceof RegExp; },
+  isMap(v) { return v instanceof Map; },
+  isSet(v) { return v instanceof Set; },
+  isSymbol(v) { return typeof v === 'symbol'; },
+  isPromise(v) { return v && typeof v.then === 'function'; },
+  isInteger(v) { return Number.isInteger(v); },
+  isFinite(v) { return Number.isFinite(v); },
+  isPlainObject(v) {
+    if (!v || typeof v !== 'object') return false;
+    const proto = Object.getPrototypeOf(v);
+    return proto === Object.prototype || proto === null;
+  },
+
+  // ==========================================
+  // STRING / CSS UTILITIES
+  // ==========================================
+
+  /**
+   * classNames — like clsx/classnames. Combines class names conditionally.
+   * 
+   * @example
+   * _.classNames('btn', { active: true, disabled: false }, 'primary');
+   * // => 'btn active primary'
+   * 
+   * _.classNames(['flex', condition && 'hidden']);
+   * // => 'flex hidden' (if condition is true)
+   */
+  classNames(...args) {
+    const classes = [];
+    for (const arg of args) {
+      if (!arg) continue;
+      if (typeof arg === 'string') {
+        classes.push(arg);
+      } else if (Array.isArray(arg)) {
+        const inner = _.classNames(...arg);
+        if (inner) classes.push(inner);
+      } else if (typeof arg === 'object') {
+        for (const [key, val] of Object.entries(arg)) {
+          if (val) classes.push(key);
+        }
+      }
+    }
+    return classes.join(' ');
+  },
+
+  /** Alias for classNames */
+  clsx(...args) {
+    return _.classNames(...args);
+  },
+
+  // ==========================================
+  // MISC
+  // ==========================================
+
+  /** No-op function */
+  noop() {},
+
+  /** Identity function */
+  identity(v) { return v; },
+
+  /** Constant function */
+  constant(v) { return () => v; },
+
+  /** Generate unique ID (incrementing) */
+  _idCounter: 0,
+  uniqueId(prefix = '') {
+    _._idCounter++;
+    return `${prefix}${_._idCounter}`;
+  },
+
+  /** Safe JSON parse */
+  tryParse(str, defaultValue = null) {
+    try { return JSON.parse(str); } catch { return defaultValue; }
+  },
+
+  /** Convert object to query string */
+  toQueryString(obj) {
+    return Object.entries(obj)
+      .filter(([, v]) => v !== undefined && v !== null)
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
+      .join('&');
+  },
+
+  /** Parse query string to object */
+  parseQueryString(str) {
+    const result = {};
+    const query = str.startsWith('?') ? str.slice(1) : str;
+    for (const pair of query.split('&')) {
+      const [key, value] = pair.split('=').map(decodeURIComponent);
+      if (key) result[key] = value || '';
+    }
+    return result;
+  },
+
+  /** Sleep / wait */
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  },
+};
+
+module.exports = { _, Collection: _ };