@bquery/bquery 1.2.0 → 1.4.0

package/src/core/utils/function.ts

@@ -0,0 +1,151 @@
+/**
+ * Function-focused utility helpers.
+ *
+ * @module bquery/core/utils/function
+ */
+
+/** A debounced function with a cancel method to clear the pending timeout. */
+export interface DebouncedFn<TArgs extends unknown[]> {
+  (...args: TArgs): void;
+  /** Cancels the pending debounced invocation. */
+  cancel(): void;
+}
+
+/** A throttled function with a cancel method to reset the throttle timer. */
+export interface ThrottledFn<TArgs extends unknown[]> {
+  (...args: TArgs): void;
+  /** Resets the throttle timer, allowing the next call to execute immediately. */
+  cancel(): void;
+}
+
+/**
+ * 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 with a `cancel()` method
+ *
+ * @example
+ * ```ts
+ * const search = debounce((query: string) => {
+ *   console.log('Searching:', query);
+ * }, 300);
+ *
+ * search('h');
+ * search('he');
+ * search('hello'); // Only this call executes after 300ms
+ *
+ * search('cancel me');
+ * search.cancel(); // Cancels the pending invocation
+ * ```
+ */
+export function debounce<TArgs extends unknown[]>(
+  fn: (...args: TArgs) => void,
+  delayMs: number
+): DebouncedFn<TArgs> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  const debounced: DebouncedFn<TArgs> = Object.assign(
+    (...args: TArgs) => {
+      if (timeoutId !== undefined) {
+        clearTimeout(timeoutId);
+      }
+      timeoutId = setTimeout(() => {
+        timeoutId = undefined;
+        fn(...args);
+      }, delayMs);
+    },
+    {
+      cancel: () => {
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId);
+          timeoutId = undefined;
+        }
+      },
+    }
+  );
+  return debounced;
+}
+
+/**
+ * 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 with a `cancel()` method
+ *
+ * @example
+ * ```ts
+ * const handleScroll = throttle(() => {
+ *   console.log('Scroll position:', window.scrollY);
+ * }, 100);
+ *
+ * window.addEventListener('scroll', handleScroll);
+ *
+ * handleScroll.cancel(); // Resets throttle, next call executes immediately
+ * ```
+ */
+export function throttle<TArgs extends unknown[]>(
+  fn: (...args: TArgs) => void,
+  intervalMs: number
+): ThrottledFn<TArgs> {
+  let lastRun = 0;
+  const throttled: ThrottledFn<TArgs> = Object.assign(
+    (...args: TArgs) => {
+      const now = Date.now();
+      if (now - lastRun >= intervalMs) {
+        lastRun = now;
+        fn(...args);
+      }
+    },
+    {
+      cancel: () => {
+        lastRun = 0;
+      },
+    }
+  );
+  return throttled;
+}
+
+/**
+ * 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);
+}

package/src/core/utils/string.ts

@@ -0,0 +1,112 @@
+/**
+ * String-focused utility helpers.
+ *
+ * @module bquery/core/utils/string
+ */
+
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns The capitalized string
+ *
+ * @example
+ * ```ts
+ * capitalize('hello'); // 'Hello'
+ * ```
+ */
+export function capitalize(str: string): string {
+  if (!str) return str;
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Converts a string to kebab-case.
+ *
+ * @param str - The string to convert
+ * @returns The kebab-cased string
+ *
+ * @example
+ * ```ts
+ * toKebabCase('myVariableName'); // 'my-variable-name'
+ * ```
+ */
+export function toKebabCase(str: string): string {
+  return str
+    .replace(/([a-z])([A-Z])/g, '$1-$2')
+    .replace(/[\s_]+/g, '-')
+    .toLowerCase();
+}
+
+/**
+ * Converts a string to camelCase.
+ *
+ * @param str - The string to convert
+ * @returns The camelCased string
+ *
+ * @example
+ * ```ts
+ * toCamelCase('my-variable-name'); // 'myVariableName'
+ * ```
+ */
+export function toCamelCase(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, char) => (char ? char.toUpperCase() : ''))
+    .replace(/^[A-Z]/, (char) => char.toLowerCase());
+}
+
+/**
+ * Truncates a string to a maximum length.
+ *
+ * @param str - The string to truncate
+ * @param maxLength - The maximum length
+ * @param suffix - The suffix to append when truncating (default: '…')
+ * @returns The truncated string
+ *
+ * @example
+ * ```ts
+ * truncate('Hello world', 8); // 'Hello w…'
+ * ```
+ */
+export function truncate(str: string, maxLength: number, suffix = '…'): string {
+  if (maxLength <= 0) return '';
+  if (str.length <= maxLength) return str;
+  const sliceLength = Math.max(0, maxLength - suffix.length);
+  return `${str.slice(0, sliceLength)}${suffix}`;
+}
+
+/**
+ * Converts a string to a URL-friendly slug.
+ *
+ * @param str - The string to slugify
+ * @returns The slugified string
+ *
+ * @example
+ * ```ts
+ * slugify('Hello, World!'); // 'hello-world'
+ * ```
+ */
+export function slugify(str: string): string {
+  return str
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^\w\s-]/g, '')
+    .trim()
+    .replace(/[\s_-]+/g, '-')
+    .toLowerCase();
+}
+
+/**
+ * Escapes a string for safe usage inside a RegExp.
+ *
+ * @param str - The string to escape
+ * @returns The escaped string
+ *
+ * @example
+ * ```ts
+ * escapeRegExp('[a-z]+'); // '\\[a-z\\]+'
+ * ```
+ */
+export function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}