elementdrawing 1.0.0

package/src/js/utils.js

@@ -0,0 +1,593 @@
+/**
+ * General Utility Functions
+ * ElementDrawing Framework - Type checking, object/array/string/number/function/
+ * date/color/URL utilities for comprehensive data manipulation.
+ */
+
+'use strict';
+
+// ─── Type Checking ────────────────────────────────────────────────────────────
+
+const isString = (v) => typeof v === 'string';
+const isNumber = (v) => typeof v === 'number' && !isNaN(v);
+const isBoolean = (v) => typeof v === 'boolean';
+const isFunction = (v) => typeof v === 'function';
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isArray = Array.isArray;
+const isNull = (v) => v === null;
+const isUndefined = (v) => v === undefined;
+const isDate = (v) => v instanceof Date && !isNaN(v.getTime());
+const isRegExp = (v) => v instanceof RegExp;
+const isPromise = (v) => v && typeof v.then === 'function';
+const isElement = (v) => v instanceof HTMLElement || v instanceof SVGElement;
+const isPlainObject = (v) => Object.prototype.toString.call(v) === '[object Object]';
+const isNil = (v) => v === null || v === undefined;
+const isFiniteNum = (v) => Number.isFinite(v);
+const isInteger = Number.isInteger;
+
+// ─── Object Utilities ─────────────────────────────────────────────────────────
+
+function deepClone(obj, cache) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (isDate(obj)) return new Date(obj.getTime());
+  if (isRegExp(obj)) return new RegExp(obj.source, obj.flags);
+  if (isElement(obj)) return obj;
+
+  cache = cache || new WeakMap();
+  if (cache.has(obj)) return cache.get(obj);
+
+  const clone = Array.isArray(obj) ? [] : {};
+  cache.set(obj, clone);
+
+  Object.keys(obj).forEach((key) => {
+    clone[key] = deepClone(obj[key], cache);
+  });
+  return clone;
+}
+
+function deepMerge(target) {
+  const sources = Array.prototype.slice.call(arguments, 1);
+  sources.forEach((source) => {
+    if (!isObject(source)) return;
+    Object.keys(source).forEach((key) => {
+      if (isObject(source[key]) && isObject(target[key])) {
+        target[key] = deepMerge({}, target[key], source[key]);
+      } else {
+        target[key] = source[key];
+      }
+    });
+  });
+  return target;
+}
+
+function shallowMerge(target) {
+  const sources = Array.prototype.slice.call(arguments, 1);
+  sources.forEach((source) => {
+    if (!source) return;
+    Object.keys(source).forEach((key) => { target[key] = source[key]; });
+  });
+  return target;
+}
+
+function pick(obj, keys) {
+  const result = {};
+  keys.forEach((key) => {
+    if (obj && Object.prototype.hasOwnProperty.call(obj, key)) {
+      result[key] = obj[key];
+    }
+  });
+  return result;
+}
+
+function omit(obj, keys) {
+  const keySet = new Set(keys);
+  const result = {};
+  Object.keys(obj).forEach((key) => {
+    if (!keySet.has(key)) result[key] = obj[key];
+  });
+  return result;
+}
+
+function get(obj, path, defaultValue) {
+  const keys = path.replace(/\[(\d+)\]/g, '.$1').split('.');
+  let result = obj;
+  for (let i = 0; i < keys.length; i++) {
+    if (result == null) return defaultValue;
+    result = result[keys[i]];
+  }
+  return result === undefined ? defaultValue : result;
+}
+
+function set(obj, path, value) {
+  const keys = path.replace(/\[(\d+)\]/g, '.$1').split('.');
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (!current[keys[i]]) current[keys[i]] = {};
+    current = current[keys[i]];
+  }
+  current[keys[keys.length - 1]] = value;
+  return obj;
+}
+
+function has(obj, path) {
+  const keys = path.replace(/\[(\d+)\]/g, '.$1').split('.');
+  let current = obj;
+  for (let i = 0; i < keys.length; i++) {
+    if (current == null || !Object.prototype.hasOwnProperty.call(current, keys[i])) return false;
+    current = current[keys[i]];
+  }
+  return true;
+}
+
+const keys = Object.keys;
+const values = Object.values;
+const entries = Object.entries;
+const fromEntries = Object.fromEntries;
+
+function isEmpty(obj) {
+  if (obj == null) return true;
+  if (isArray(obj) || isString(obj)) return obj.length === 0;
+  if (isObject(obj)) return Object.keys(obj).length === 0;
+  return false;
+}
+
+function isEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a == null || b == null) return false;
+  if (typeof a !== typeof b) return false;
+  if (isDate(a) && isDate(b)) return a.getTime() === b.getTime();
+  if (isRegExp(a) && isRegExp(b)) return a.source === b.source && a.flags === b.flags;
+  if (isArray(a) && isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((v, i) => isEqual(v, b[i]));
+  }
+  if (isObject(a) && isObject(b)) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every((key) => isEqual(a[key], b[key]));
+  }
+  return false;
+}
+
+function flattenObject(obj, prefix) {
+  prefix = prefix || '';
+  const result = {};
+  Object.keys(obj).forEach((key) => {
+    const path = prefix ? prefix + '.' + key : key;
+    if (isObject(obj[key]) && !isDate(obj[key]) && !isRegExp(obj[key])) {
+      Object.assign(result, flattenObject(obj[key], path));
+    } else {
+      result[path] = obj[key];
+    }
+  });
+  return result;
+}
+
+// ─── Array Utilities ──────────────────────────────────────────────────────────
+
+function unique(arr) { return Array.from(new Set(arr)); }
+function flatten(arr, depth) { return arr.flat(depth !== undefined ? depth : Infinity); }
+
+function chunk(arr, size) {
+  const result = [];
+  for (let i = 0; i < arr.length; i += size) {
+    result.push(arr.slice(i, i + size));
+  }
+  return result;
+}
+
+function groupBy(arr, key) {
+  return arr.reduce((groups, item) => {
+    const val = typeof key === 'function' ? key(item) : item[key];
+    (groups[val] = groups[val] || []).push(item);
+    return groups;
+  }, {});
+}
+
+function sortBy(arr, key, order) {
+  return arr.slice().sort((a, b) => {
+    const aVal = typeof key === 'function' ? key(a) : a[key];
+    const bVal = typeof key === 'function' ? key(b) : b[key];
+    const cmp = aVal < bVal ? -1 : aVal > bVal ? 1 : 0;
+    return order === 'desc' ? -cmp : cmp;
+  });
+}
+
+function filterBy(arr, key, value) {
+  if (typeof key === 'function') return arr.filter(key);
+  return arr.filter((item) => item[key] === value);
+}
+
+function findBy(arr, key, value) {
+  if (typeof key === 'function') return arr.find(key);
+  return arr.find((item) => item[key] === value);
+}
+
+function countBy(arr, key) {
+  return arr.reduce((counts, item) => {
+    const val = typeof key === 'function' ? key(item) : item[key];
+    counts[val] = (counts[val] || 0) + 1;
+    return counts;
+  }, {});
+}
+
+function partition(arr, predicate) {
+  const pass = [], fail = [];
+  arr.forEach((item) => (predicate(item) ? pass : fail).push(item));
+  return [pass, fail];
+}
+
+function zip() {
+  const arrays = Array.prototype.slice.call(arguments);
+  const len = Math.min.apply(null, arrays.map((a) => a.length));
+  const result = [];
+  for (let i = 0; i < len; i++) {
+    result.push(arrays.map((a) => a[i]));
+  }
+  return result;
+}
+
+function unzip(arr) {
+  const len = Math.max.apply(null, arr.map((a) => a.length));
+  const result = [];
+  for (let i = 0; i < len; i++) {
+    result.push(arr.map((a) => a[i]));
+  }
+  return result;
+}
+
+function difference(a, b) { return a.filter((x) => !b.includes(x)); }
+function intersection(a, b) { return a.filter((x) => b.includes(x)); }
+function union(a, b) { return unique(a.concat(b)); }
+
+function shuffle(arr) {
+  const result = arr.slice();
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    const tmp = result[i]; result[i] = result[j]; result[j] = tmp;
+  }
+  return result;
+}
+
+function sample(arr, n) {
+  if (n === undefined) return arr[Math.floor(Math.random() * arr.length)];
+  return shuffle(arr).slice(0, n);
+}
+
+function range(start, end, step) {
+  if (end === undefined) { end = start; start = 0; }
+  step = step || 1;
+  const result = [];
+  for (let i = start; step > 0 ? i < end : i > end; i += step) {
+    result.push(i);
+  }
+  return result;
+}
+
+// ─── String Utilities ─────────────────────────────────────────────────────────
+
+function capitalize(str) {
+  return str ? str.charAt(0).toUpperCase() + str.slice(1) : '';
+}
+
+function camelCase(str) {
+  return str.replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : '');
+}
+
+function kebabCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2').replace(/[\s_]+/g, '-').toLowerCase();
+}
+
+function snakeCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, '$1_$2').replace(/[\s-]+/g, '_').toLowerCase();
+}
+
+function pascalCase(str) {
+  return camelCase(str).replace(/^(.)/, (_, c) => c.toUpperCase());
+}
+
+function truncate(str, len, suffix) {
+  suffix = suffix || '...';
+  return str.length <= len ? str : str.slice(0, len - suffix.length) + suffix;
+}
+
+function padStart(str, len, fill) { return String(str).padStart(len, fill || ' '); }
+function padEnd(str, len, fill) { return String(str).padEnd(len, fill || ' '); }
+function trim(str, chars) {
+  if (!chars) return String(str).trim();
+  const re = new RegExp('^[' + chars + ']+|[' + chars + ']+$', 'g');
+  return String(str).replace(re, '');
+}
+function repeat(str, n) { return String(str).repeat(n); }
+
+function template(str, data) {
+  return str.replace(/\{\{(\w+)\}\}/g, (_, key) => data[key] !== undefined ? data[key] : '');
+}
+
+function escapeHtml(str) {
+  const map = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+  return String(str).replace(/[&<>"']/g, (c) => map[c]);
+}
+
+function unescapeHtml(str) {
+  const map = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'" };
+  return String(str).replace(/&(?:amp|lt|gt|quot|#39);/g, (c) => map[c]);
+}
+
+function formatNumber(num, decimals, sep) {
+  decimals = decimals !== undefined ? decimals : 2;
+  sep = sep || ',';
+  const parts = Number(num).toFixed(decimals).split('.');
+  parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, sep);
+  return parts.join('.');
+}
+
+function formatCurrency(num, symbol, decimals) {
+  symbol = symbol || '$';
+  return symbol + formatNumber(num, decimals || 2);
+}
+
+// ─── Number Utilities ─────────────────────────────────────────────────────────
+
+function clamp(num, min, max) { return Math.min(Math.max(num, min), max); }
+function random(min, max) { return Math.random() * (max - min) + min; }
+function randomInt(min, max) { return Math.floor(random(min, max + 1)); }
+function round(num, decimals) { const f = Math.pow(10, decimals || 0); return Math.round(num * f) / f; }
+function ceil(num, decimals) { const f = Math.pow(10, decimals || 0); return Math.ceil(num * f) / f; }
+function floor(num, decimals) { const f = Math.pow(10, decimals || 0); return Math.floor(num * f) / f; }
+function sum(arr) { return arr.reduce((a, b) => a + b, 0); }
+function avg(arr) { return arr.length ? sum(arr) / arr.length : 0; }
+function min(arr) { return Math.min.apply(null, arr); }
+function max(arr) { return Math.max.apply(null, arr); }
+function percent(value, total) { return total === 0 ? 0 : (value / total) * 100; }
+function isBetween(num, lo, hi) { return num >= lo && num <= hi; }
+function lerp(a, b, t) { return a + (b - a) * t; }
+function toFixed(num, d) { return Number(Number(num).toFixed(d || 0)); }
+
+// ─── Function Utilities ───────────────────────────────────────────────────────
+
+function debounce(fn, delay) {
+  let timer;
+  const debounced = function () {
+    const args = arguments, ctx = this;
+    clearTimeout(timer);
+    timer = setTimeout(() => fn.apply(ctx, args), delay);
+  };
+  debounced.cancel = () => clearTimeout(timer);
+  debounced.flush = function () { clearTimeout(timer); fn.apply(this, arguments); };
+  return debounced;
+}
+
+function throttle(fn, limit) {
+  let lastTime = 0, timer;
+  return function () {
+    const now = Date.now(), args = arguments, ctx = this;
+    if (now - lastTime >= limit) {
+      clearTimeout(timer);
+      lastTime = now;
+      fn.apply(ctx, args);
+    } else if (!timer) {
+      timer = setTimeout(() => { lastTime = now; timer = null; fn.apply(ctx, args); }, limit - (now - lastTime));
+    }
+  };
+}
+
+function memoize(fn, resolver) {
+  const cache = new Map();
+  const memoized = function () {
+    const key = resolver ? resolver.apply(null, arguments) : JSON.stringify(arguments);
+    if (cache.has(key)) return cache.get(key);
+    const result = fn.apply(this, arguments);
+    cache.set(key, result);
+    return result;
+  };
+  memoized.cache = cache;
+  memoized.clear = () => cache.clear();
+  return memoized;
+}
+
+function once(fn) {
+  let called = false, result;
+  return function () {
+    if (called) return result;
+    called = true;
+    result = fn.apply(this, arguments);
+    return result;
+  };
+}
+
+function curry(fn) {
+  const arity = fn.length;
+  return function curried() {
+    const args = Array.prototype.slice.call(arguments);
+    if (args.length >= arity) return fn.apply(this, args);
+    return function () { return curried.apply(this, args.concat(Array.prototype.slice.call(arguments))); };
+  };
+}
+
+function compose() {
+  const fns = Array.prototype.slice.call(arguments);
+  return function (x) { return fns.reduceRight((v, f) => f(v), x); };
+}
+
+function pipe() {
+  const fns = Array.prototype.slice.call(arguments);
+  return function (x) { return fns.reduce((v, f) => f(v), x); };
+}
+
+function partial(fn) {
+  const preset = Array.prototype.slice.call(arguments, 1);
+  return function () { return fn.apply(this, preset.concat(Array.prototype.slice.call(arguments))); };
+}
+
+function noop() {}
+function identity(v) { return v; }
+
+// ─── Date Utilities ───────────────────────────────────────────────────────────
+
+function formatDate(date, format) {
+  date = isDate(date) ? date : new Date(date);
+  if (isNaN(date.getTime())) return '';
+  format = format || 'YYYY-MM-DD';
+  const pad = (n) => String(n).padStart(2, '0');
+  const tokens = {
+    'YYYY': date.getFullYear(), 'MM': pad(date.getMonth() + 1), 'DD': pad(date.getDate()),
+    'HH': pad(date.getHours()), 'mm': pad(date.getMinutes()), 'ss': pad(date.getSeconds()),
+  };
+  let result = format;
+  Object.keys(tokens).forEach((key) => { result = result.replace(key, tokens[key]); });
+  return result;
+}
+
+function parseDate(str, format) {
+  if (!format) return new Date(str);
+  const map = {};
+  format.replace(/(YYYY|MM|DD|HH|mm|ss)/g, (m, p, o) => { map[p] = o; return m; });
+  const y = str.substr(map.YYYY, 4), mo = str.substr(map.MM, 2), d = str.substr(map.DD, 2);
+  return new Date(y, mo - 1, d);
+}
+
+function addDays(date, days) { const d = new Date(date); d.setDate(d.getDate() + days); return d; }
+function diffDays(a, b) { return Math.round((new Date(a) - new Date(b)) / 86400000); }
+function isToday(date) { const d = new Date(date), t = new Date(); return d.toDateString() === t.toDateString(); }
+function isWeekend(date) { const day = new Date(date).getDay(); return day === 0 || day === 6; }
+function getWeek(date) { const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())); d.setUTCDate(d.getUTCDate() + 4 - (d.getUTCDay() || 7)); return Math.ceil(((d - new Date(Date.UTC(d.getUTCFullYear(), 0, 1))) / 86400000 + 1) / 7); }
+function getQuarter(date) { return Math.ceil((new Date(date).getMonth() + 1) / 3); }
+
+// ─── Color Utilities ──────────────────────────────────────────────────────────
+
+function hexToRgb(hex) {
+  hex = hex.replace('#', '');
+  if (hex.length === 3) hex = hex.split('').map((c) => c + c).join('');
+  const n = parseInt(hex, 16);
+  return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+}
+
+function rgbToHex(r, g, b) {
+  return '#' + [r, g, b].map((c) => Math.max(0, Math.min(255, Math.round(c))).toString(16).padStart(2, '0')).join('');
+}
+
+function hexToHsl(hex) {
+  const { r, g, b } = hexToRgb(hex);
+  const rn = r / 255, gn = g / 255, bn = b / 255;
+  const max = Math.max(rn, gn, bn), min = Math.min(rn, gn, bn);
+  let h, s, l = (max + min) / 2;
+  if (max === min) { h = s = 0; } else {
+    const d = max - min;
+    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    switch (max) {
+      case rn: h = ((gn - bn) / d + (gn < bn ? 6 : 0)) / 6; break;
+      case gn: h = ((bn - rn) / d + 2) / 6; break;
+      case bn: h = ((rn - gn) / d + 4) / 6; break;
+    }
+  }
+  return { h: Math.round(h * 360), s: Math.round(s * 100), l: Math.round(l * 100) };
+}
+
+function hslToHex(h, s, l) {
+  s /= 100; l /= 100;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => {
+    const k = (n + h / 30) % 12;
+    const color = l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
+    return Math.round(255 * color).toString(16).padStart(2, '0');
+  };
+  return '#' + f(0) + f(8) + f(4);
+}
+
+function lighten(hex, amount) {
+  const { r, g, b } = hexToRgb(hex);
+  return rgbToHex(r + (255 - r) * amount / 100, g + (255 - g) * amount / 100, b + (255 - b) * amount / 100);
+}
+
+function darken(hex, amount) {
+  const { r, g, b } = hexToRgb(hex);
+  return rgbToHex(r * (1 - amount / 100), g * (1 - amount / 100), b * (1 - amount / 100));
+}
+
+function alpha(hex, a) {
+  const { r, g, b } = hexToRgb(hex);
+  return 'rgba(' + r + ',' + g + ',' + b + ',' + a + ')';
+}
+
+function isValidColor(str) {
+  if (!str) return false;
+  if (/^#([0-9A-Fa-f]{3}){1,2}$/.test(str)) return true;
+  if (/^rgb\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*\)$/.test(str)) return true;
+  if (/^rgba\(\s*\d+\s*,\s*\d+\s*,\s*\d+\s*,\s*[\d.]+\s*\)$/.test(str)) return true;
+  if (/^hsl\(\s*\d+\s*,\s*\d+%\s*,\s*\d+%\s*\)$/.test(str)) return true;
+  const opt = new Option();
+  opt.style.color = str;
+  return opt.style.color !== '';
+}
+
+// ─── URL Utilities ────────────────────────────────────────────────────────────
+
+function parseUrl(url) {
+  try { return new URL(url); } catch (e) { return null; }
+}
+
+function buildUrl(base, path, params) {
+  let url = base;
+  if (path) url = url.replace(/\/$/, '') + '/' + path.replace(/^\//, '');
+  if (params) {
+    const qs = Object.keys(params).map((k) => encodeURIComponent(k) + '=' + encodeURIComponent(params[k])).join('&');
+    if (qs) url += (url.includes('?') ? '&' : '?') + qs;
+  }
+  return url;
+}
+
+function getQueryParam(name, url) {
+  url = url || window.location.href;
+  const u = new URL(url);
+  return u.searchParams.get(name);
+}
+
+function setQueryParam(name, value, url) {
+  url = url || window.location.href;
+  const u = new URL(url);
+  u.searchParams.set(name, value);
+  return u.toString();
+}
+
+function getHash(url) {
+  url = url || window.location.href;
+  const idx = url.indexOf('#');
+  return idx !== -1 ? url.slice(idx + 1) : '';
+}
+
+function setHash(hash, url) {
+  url = url || window.location.href;
+  const idx = url.indexOf('#');
+  const base = idx !== -1 ? url.slice(0, idx) : url;
+  return base + '#' + hash;
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  // Type checking
+  isString, isNumber, isBoolean, isFunction, isObject, isArray, isNull, isUndefined,
+  isDate, isRegExp, isPromise, isElement, isPlainObject, isNil, isFiniteNum, isInteger,
+  // Object utilities
+  deepClone, deepMerge, shallowMerge, pick, omit, get, set, has, keys, values,
+  entries, fromEntries, isEmpty, isEqual, flattenObject,
+  // Array utilities
+  unique, flatten, chunk, groupBy, sortBy, filterBy, findBy, countBy, partition,
+  zip, unzip, difference, intersection, union, shuffle, sample, range,
+  // String utilities
+  capitalize, camelCase, kebabCase, snakeCase, pascalCase, truncate, padStart,
+  padEnd, trim, repeat, template, escapeHtml, unescapeHtml, formatNumber, formatCurrency,
+  // Number utilities
+  clamp, random, randomInt, round, ceil, floor, sum, avg, min, max, percent,
+  isBetween, lerp, toFixed,
+  // Function utilities
+  debounce, throttle, memoize, once, curry, compose, pipe, partial, noop, identity,
+  // Date utilities
+  formatDate, parseDate, addDays, diffDays, isToday, isWeekend, getWeek, getQuarter,
+  // Color utilities
+  hexToRgb, rgbToHex, hexToHsl, hslToHex, lighten, darken, alpha, isValidColor,
+  // URL utilities
+  parseUrl, buildUrl, getQueryParam, setQueryParam, getHash, setHash,
+};