@bquery/bquery 1.2.0 → 1.3.0

package/src/core/index.ts

@@ -1,4 +1,47 @@
 export { BQueryCollection } from './collection';
 export { BQueryElement } from './element';
 export { $, $$ } from './selector';
+// Re-export the utils namespace for backward compatibility
 export { utils } from './utils';
+// Export individual utilities (except internal helpers)
+export {
+  chunk,
+  compact,
+  ensureArray,
+  flatten,
+  unique,
+  debounce,
+  noop,
+  once,
+  throttle,
+  isEmpty,
+  parseJson,
+  sleep,
+  uid,
+  clamp,
+  inRange,
+  randomInt,
+  toNumber,
+  clone,
+  hasOwn,
+  isPlainObject,
+  merge,
+  omit,
+  pick,
+  capitalize,
+  escapeRegExp,
+  slugify,
+  toCamelCase,
+  toKebabCase,
+  truncate,
+  isArray,
+  isBoolean,
+  isCollection,
+  isDate,
+  isElement,
+  isFunction,
+  isNumber,
+  isObject,
+  isPromise,
+  isString,
+} from './utils';

package/src/core/utils/array.ts

@@ -0,0 +1,102 @@
+/**
+ * Array-focused utility helpers.
+ *
+ * @module bquery/core/utils/array
+ */
+
+/**
+ * Ensures the input is always returned as an array.
+ *
+ * @template T - The item type
+ * @param value - A single value, array, or nullish value
+ * @returns An array (empty if nullish)
+ *
+ * @example
+ * ```ts
+ * ensureArray('a'); // ['a']
+ * ensureArray(['a', 'b']); // ['a', 'b']
+ * ensureArray(null); // []
+ * ```
+ */
+export function ensureArray<T>(value: T | T[] | null | undefined): T[] {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Removes duplicate entries from an array.
+ *
+ * @template T - The item type
+ * @param items - The array to deduplicate
+ * @returns A new array with unique items
+ *
+ * @example
+ * ```ts
+ * unique([1, 2, 2, 3]); // [1, 2, 3]
+ * ```
+ */
+export function unique<T>(items: T[]): T[] {
+  return Array.from(new Set(items));
+}
+
+/**
+ * Splits an array into chunks of a given size.
+ *
+ * @template T - The item type
+ * @param items - The array to chunk
+ * @param size - The maximum size of each chunk
+ * @returns An array of chunks
+ *
+ * @example
+ * ```ts
+ * chunk([1, 2, 3, 4, 5], 2); // [[1,2],[3,4],[5]]
+ * ```
+ */
+export function chunk<T>(items: T[], size: number): T[][] {
+  if (size <= 0) return [];
+  const result: T[][] = [];
+  for (let i = 0; i < items.length; i += size) {
+    result.push(items.slice(i, i + size));
+  }
+  return result;
+}
+
+/**
+ * Removes falsy values from an array.
+ *
+ * @template T - The item type
+ * @param items - The array to compact
+ * @returns A new array without falsy values
+ *
+ * @example
+ * ```ts
+ * compact([0, 1, '', 'ok', null]); // [1, 'ok']
+ * ```
+ */
+export function compact<T>(items: Array<T | null | undefined | false | 0 | ''>): T[] {
+  return items.filter(Boolean) as T[];
+}
+
+/**
+ * Flattens a single level of nested arrays.
+ *
+ * @template T - The item type
+ * @param items - The array to flatten
+ * @returns A new flattened array
+ *
+ * @example
+ * ```ts
+ * flatten([1, [2, 3], 4]); // [1, 2, 3, 4]
+ * ```
+ */
+export function flatten<T>(items: Array<T | T[]>): T[] {
+  const result: T[] = [];
+  for (const item of items) {
+    if (Array.isArray(item)) {
+      result.push(...item);
+    } else {
+      result.push(item);
+    }
+  }
+  return result;
+}

package/src/core/utils/function.ts

@@ -0,0 +1,110 @@
+/**
+ * Function-focused utility helpers.
+ *
+ * @module bquery/core/utils/function
+ */
+
+/**
+ * Creates a debounced function that delays execution until after
+ * the specified delay has elapsed since the last call.
+ *
+ * @template TArgs - The argument types of the function
+ * @param fn - The function to debounce
+ * @param delayMs - Delay in milliseconds
+ * @returns A debounced version of the function
+ *
+ * @example
+ * ```ts
+ * const search = debounce((query: string) => {
+ *   console.log('Searching:', query);
+ * }, 300);
+ *
+ * search('h');
+ * search('he');
+ * search('hello'); // Only this call executes after 300ms
+ * ```
+ */
+export function debounce<TArgs extends unknown[]>(
+  fn: (...args: TArgs) => void,
+  delayMs: number
+): (...args: TArgs) => void {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  return (...args: TArgs) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+    timeoutId = setTimeout(() => fn(...args), delayMs);
+  };
+}
+
+/**
+ * Creates a throttled function that runs at most once per interval.
+ *
+ * @template TArgs - The argument types of the function
+ * @param fn - The function to throttle
+ * @param intervalMs - Minimum interval between calls in milliseconds
+ * @returns A throttled version of the function
+ *
+ * @example
+ * ```ts
+ * const handleScroll = throttle(() => {
+ *   console.log('Scroll position:', window.scrollY);
+ * }, 100);
+ *
+ * window.addEventListener('scroll', handleScroll);
+ * ```
+ */
+export function throttle<TArgs extends unknown[]>(
+  fn: (...args: TArgs) => void,
+  intervalMs: number
+): (...args: TArgs) => void {
+  let lastRun = 0;
+  return (...args: TArgs) => {
+    const now = Date.now();
+    if (now - lastRun >= intervalMs) {
+      lastRun = now;
+      fn(...args);
+    }
+  };
+}
+
+/**
+ * Ensures a function only runs once. Subsequent calls return the first result.
+ *
+ * @template TArgs - The argument types of the function
+ * @template TResult - The return type of the function
+ * @param fn - The function to wrap
+ * @returns A function that only runs once
+ *
+ * @example
+ * ```ts
+ * const init = once(() => ({ ready: true }));
+ * init();
+ * init(); // only runs once
+ * ```
+ */
+export function once<TArgs extends unknown[], TResult>(
+  fn: (...args: TArgs) => TResult
+): (...args: TArgs) => TResult {
+  let hasRun = false;
+  let result!: TResult;
+  return (...args: TArgs) => {
+    if (!hasRun) {
+      result = fn(...args);
+      hasRun = true;
+    }
+    return result;
+  };
+}
+
+/**
+ * A no-operation function.
+ *
+ * @example
+ * ```ts
+ * noop();
+ * ```
+ */
+export function noop(): void {
+  // Intentionally empty
+}

package/src/core/utils/index.ts

@@ -0,0 +1,83 @@
+/**
+ * Utility helpers used across the framework.
+ * These are intentionally small and framework-agnostic to keep the core tiny.
+ *
+ * @module bquery/core/utils
+ */
+
+export * from './array';
+export * from './function';
+export * from './misc';
+export * from './number';
+export * from './object';
+export * from './string';
+export * from './type-guards';
+
+import { chunk, compact, ensureArray, flatten, unique } from './array';
+import { debounce, noop, once, throttle } from './function';
+import { isEmpty, parseJson, sleep, uid } from './misc';
+import { clamp, inRange, randomInt, toNumber } from './number';
+import { clone, hasOwn, isPlainObject, merge, omit, pick } from './object';
+import { capitalize, escapeRegExp, slugify, toCamelCase, toKebabCase, truncate } from './string';
+import {
+  isArray,
+  isBoolean,
+  isCollection,
+  isDate,
+  isElement,
+  isFunction,
+  isNumber,
+  isObject,
+  isPromise,
+  isString,
+} from './type-guards';
+
+/**
+ * Utility object containing common helper functions.
+ * All utilities are designed to be tree-shakeable and have zero dependencies.
+ *
+ * Note: `isPrototypePollutionKey` is intentionally excluded from this namespace
+ * as it is an internal security helper. It remains available as a named export
+ * for internal framework use.
+ */
+export const utils = {
+  clone,
+  merge,
+  pick,
+  omit,
+  hasOwn,
+  debounce,
+  throttle,
+  once,
+  noop,
+  uid,
+  isElement,
+  isCollection,
+  isEmpty,
+  isPlainObject,
+  isFunction,
+  isString,
+  isNumber,
+  isBoolean,
+  isArray,
+  isDate,
+  isPromise,
+  isObject,
+  parseJson,
+  sleep,
+  randomInt,
+  clamp,
+  inRange,
+  toNumber,
+  capitalize,
+  toKebabCase,
+  toCamelCase,
+  truncate,
+  slugify,
+  escapeRegExp,
+  ensureArray,
+  unique,
+  chunk,
+  compact,
+  flatten,
+};

package/src/core/utils/misc.ts

@@ -0,0 +1,82 @@
+/**
+ * Miscellaneous utility helpers.
+ *
+ * @module bquery/core/utils/misc
+ */
+
+/**
+ * Creates a stable unique ID for DOM usage.
+ *
+ * @param prefix - Optional prefix for the ID (default: 'bQuery')
+ * @returns A unique identifier string
+ *
+ * @example
+ * ```ts
+ * const id = uid('modal'); // 'modal_x7k2m9p'
+ * ```
+ */
+export function uid(prefix = 'bQuery'): string {
+  return `${prefix}_${Math.random().toString(36).slice(2, 9)}`;
+}
+
+/**
+ * Delays execution for a specified number of milliseconds.
+ *
+ * @param ms - Milliseconds to delay
+ * @returns A promise that resolves after the delay
+ *
+ * @example
+ * ```ts
+ * await sleep(1000); // Wait 1 second
+ * console.log('Done!');
+ * ```
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Safely parses a JSON string, returning a default value on error.
+ *
+ * @template T - The expected type of the parsed value
+ * @param json - The JSON string to parse
+ * @param fallback - The default value if parsing fails
+ * @returns The parsed value or the fallback
+ *
+ * @example
+ * ```ts
+ * parseJson('{"name":"bQuery"}', {}); // { name: 'bQuery' }
+ * parseJson('invalid', {}); // {}
+ * ```
+ */
+export function parseJson<T>(json: string, fallback: T): T {
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Checks for emptiness across common value types.
+ *
+ * @param value - The value to check
+ * @returns True if the value is empty (null, undefined, empty string, empty array, or empty object)
+ *
+ * @example
+ * ```ts
+ * isEmpty('');       // true
+ * isEmpty([]);       // true
+ * isEmpty({});       // true
+ * isEmpty(null);     // true
+ * isEmpty('hello');  // false
+ * isEmpty([1, 2]);   // false
+ * ```
+ */
+export function isEmpty(value: unknown): boolean {
+  if (value == null) return true;
+  if (typeof value === 'string') return value.trim().length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === 'object') return Object.keys(value as object).length === 0;
+  return false;
+}

package/src/core/utils/number.ts

@@ -0,0 +1,78 @@
+/**
+ * Number-focused utility helpers.
+ *
+ * @module bquery/core/utils/number
+ */
+
+/**
+ * Generates a random integer between min and max (inclusive).
+ *
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns A random integer in the range [min, max]
+ *
+ * @example
+ * ```ts
+ * const roll = randomInt(1, 6); // Random dice roll
+ * ```
+ */
+export function randomInt(min: number, max: number): number {
+  return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Clamps a number between a minimum and maximum value.
+ *
+ * @param value - The value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns The clamped value
+ *
+ * @example
+ * ```ts
+ * clamp(150, 0, 100); // 100
+ * clamp(-10, 0, 100); // 0
+ * clamp(50, 0, 100);  // 50
+ * ```
+ */
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Checks if a number is within a range.
+ *
+ * @param value - The value to check
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @param inclusive - Whether the range is inclusive (default: true)
+ * @returns True if the value is within the range
+ *
+ * @example
+ * ```ts
+ * inRange(5, 1, 10); // true
+ * inRange(10, 1, 10, false); // false
+ * ```
+ */
+export function inRange(value: number, min: number, max: number, inclusive = true): boolean {
+  if (inclusive) return value >= min && value <= max;
+  return value > min && value < max;
+}
+
+/**
+ * Converts a value to a number with a fallback on NaN.
+ *
+ * @param value - The value to convert
+ * @param fallback - The fallback value if conversion fails (default: 0)
+ * @returns The parsed number or the fallback
+ *
+ * @example
+ * ```ts
+ * toNumber('42'); // 42
+ * toNumber('nope', 10); // 10
+ * ```
+ */
+export function toNumber(value: unknown, fallback = 0): number {
+  const parsed = typeof value === 'number' ? value : Number(value);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}

package/src/core/utils/object.ts

@@ -0,0 +1,206 @@
+/**
+ * Object-focused utility helpers.
+ *
+ * @module bquery/core/utils/object
+ */
+
+/**
+ * Checks if a value is a plain object (not null, array, or class instance).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return Object.prototype.toString.call(value) === '[object Object]';
+}
+
+/**
+ * Checks if a key could cause prototype pollution.
+ * These keys are dangerous when used in object merging operations.
+ *
+ * @param key - The key to check
+ * @returns True if the key is a prototype pollution vector
+ *
+ * @internal
+ */
+export function isPrototypePollutionKey(key: string): boolean {
+  return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}
+
+/**
+ * Creates a deep clone using structuredClone if available, otherwise fallback to JSON.
+ *
+ * @template T - The type of value being cloned
+ * @param value - The value to clone
+ * @returns A deep copy of the value
+ *
+ * @remarks
+ * When `structuredClone` is available (modern browsers, Node 17+, Bun), this function
+ * provides full deep cloning including circular references, Date, Map, Set, ArrayBuffer, etc.
+ *
+ * **JSON fallback limitations** (older environments without `structuredClone`):
+ * - **Throws** on circular references
+ * - **Drops** functions, `undefined`, and Symbol properties
+ * - **Transforms** Date → ISO string, Map/Set → empty object, BigInt → throws
+ * - **Loses** prototype chains and non-enumerable properties
+ *
+ * For guaranteed safe cloning of arbitrary data, ensure your environment supports
+ * `structuredClone` or pre-validate your data structure.
+ *
+ * @example
+ * ```ts
+ * const original = { nested: { value: 1 } };
+ * const copy = clone(original);
+ * copy.nested.value = 2;
+ * console.log(original.nested.value); // 1
+ * ```
+ */
+export function clone<T>(value: T): T {
+  if (typeof structuredClone === 'function') {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value)) as T;
+}
+
+/**
+ * Deep-merges plain objects into a new object.
+ * Later sources override earlier ones for primitive values.
+ * Objects are recursively merged.
+ *
+ * @param sources - Objects to merge
+ * @returns A new object with all sources merged as an intersection type
+ *
+ * @remarks
+ * This function uses overloads to provide accurate intersection types for up to 5 sources.
+ * For more than 5 sources, the return type falls back to `Record<string, unknown>`.
+ *
+ * Note that deep merging creates a shallow intersection at the type level. Nested objects
+ * are merged at runtime, but TypeScript sees them as intersected types which may not
+ * perfectly represent the merged structure for deeply nested conflicting types.
+ *
+ * @example
+ * ```ts
+ * const result = merge(
+ *   { a: 1, nested: { x: 1 } },
+ *   { b: 2, nested: { y: 2 } }
+ * );
+ * // Result: { a: 1, b: 2, nested: { x: 1, y: 2 } }
+ * // Type: { a: number; nested: { x: number } } & { b: number; nested: { y: number } }
+ * ```
+ *
+ * @security This method is protected against prototype pollution attacks.
+ * Keys like `__proto__`, `constructor`, and `prototype` are ignored.
+ */
+export function merge<T1 extends Record<string, unknown>>(source1: T1): T1;
+export function merge<T1 extends Record<string, unknown>, T2 extends Record<string, unknown>>(
+  source1: T1,
+  source2: T2
+): T1 & T2;
+export function merge<
+  T1 extends Record<string, unknown>,
+  T2 extends Record<string, unknown>,
+  T3 extends Record<string, unknown>,
+>(source1: T1, source2: T2, source3: T3): T1 & T2 & T3;
+export function merge<
+  T1 extends Record<string, unknown>,
+  T2 extends Record<string, unknown>,
+  T3 extends Record<string, unknown>,
+  T4 extends Record<string, unknown>,
+>(source1: T1, source2: T2, source3: T3, source4: T4): T1 & T2 & T3 & T4;
+export function merge<
+  T1 extends Record<string, unknown>,
+  T2 extends Record<string, unknown>,
+  T3 extends Record<string, unknown>,
+  T4 extends Record<string, unknown>,
+  T5 extends Record<string, unknown>,
+>(source1: T1, source2: T2, source3: T3, source4: T4, source5: T5): T1 & T2 & T3 & T4 & T5;
+export function merge(...sources: Record<string, unknown>[]): Record<string, unknown>;
+export function merge(...sources: Record<string, unknown>[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const source of sources) {
+    for (const [key, value] of Object.entries(source)) {
+      if (isPrototypePollutionKey(key)) continue;
+
+      if (isPlainObject(value) && isPlainObject(result[key])) {
+        result[key] = merge(
+          result[key] as Record<string, unknown>,
+          value as Record<string, unknown>
+        );
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Picks specified keys from an object.
+ *
+ * @template T - The object type
+ * @template K - The key type
+ * @param obj - The source object
+ * @param keys - Keys to pick
+ * @returns A new object with only the specified keys
+ *
+ * @example
+ * ```ts
+ * const user = { name: 'John', age: 30, email: 'john@example.com' };
+ * pick(user, ['name', 'email']); // { name: 'John', email: 'john@example.com' }
+ * ```
+ */
+export function pick<T extends Record<string, unknown>, K extends keyof T>(
+  obj: T,
+  keys: K[]
+): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+  for (const key of keys) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Omits specified keys from an object.
+ *
+ * @template T - The object type
+ * @template K - The key type
+ * @param obj - The source object
+ * @param keys - Keys to omit
+ * @returns A new object without the specified keys
+ *
+ * @example
+ * ```ts
+ * const user = { name: 'John', age: 30, password: 'secret' };
+ * omit(user, ['password']); // { name: 'John', age: 30 }
+ * ```
+ */
+export function omit<T extends Record<string, unknown>, K extends keyof T>(
+  obj: T,
+  keys: K[]
+): Omit<T, K> {
+  const result = { ...obj };
+  for (const key of keys) {
+    delete result[key];
+  }
+  return result as Omit<T, K>;
+}
+
+/**
+ * Checks if an object has a given own property.
+ *
+ * @template T - The object type
+ * @param obj - The object to check
+ * @param key - The property key
+ * @returns True if the property exists on the object
+ *
+ * @example
+ * ```ts
+ * hasOwn({ a: 1 }, 'a'); // true
+ * ```
+ */
+export function hasOwn<T extends object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}