@bquery/bquery 1.3.0 → 1.4.0

package/src/core/index.ts

@@ -1,47 +1,48 @@
-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';
+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';
+export type { DebouncedFn, ThrottledFn } from './utils';

package/src/core/utils/function.ts

@@ -1,110 +1,151 @@
-/**
- * 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
-}
+/**
+ * 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/motion/animate.ts

@@ -1,113 +1,113 @@
-/**
- * Web Animations helpers.
- *
- * @module bquery/motion
- */
-
-import { prefersReducedMotion } from './reduced-motion';
-import type { AnimateOptions } from './types';
-
-/** @internal */
-const isStyleValue = (value: unknown): value is string | number =>
-  typeof value === 'string' || typeof value === 'number';
-
-/**
- * Convert camelCase property names to kebab-case for CSS.
- * @internal
- */
-const toKebabCase = (str: string): string => {
-  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
-};
-
-/** @internal */
-export const applyFinalKeyframeStyles = (
-  element: Element,
-  keyframes: Keyframe[] | PropertyIndexedKeyframes
-): void => {
-  const htmlElement = element as HTMLElement;
-  const style = htmlElement.style;
-
-  if (Array.isArray(keyframes)) {
-    const last = keyframes[keyframes.length - 1];
-    if (!last) return;
-    for (const [prop, value] of Object.entries(last)) {
-      if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
-      if (isStyleValue(value)) {
-        // Convert camelCase to kebab-case for CSS properties
-        const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
-        style.setProperty(cssProp, String(value));
-      }
-    }
-    return;
-  }
-
-  for (const [prop, value] of Object.entries(keyframes)) {
-    if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
-    const finalValue = Array.isArray(value) ? value[value.length - 1] : value;
-    if (isStyleValue(finalValue)) {
-      // Convert camelCase to kebab-case for CSS properties
-      const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
-      style.setProperty(cssProp, String(finalValue));
-    }
-  }
-};
-
-/**
- * Animate an element using the Web Animations API with reduced-motion fallback.
- *
- * @param element - Element to animate
- * @param config - Animation configuration
- * @returns Promise that resolves when animation completes
- *
- * @example
- * ```ts
- * await animate(element, {
- *   keyframes: [{ opacity: 0 }, { opacity: 1 }],
- *   options: { duration: 200, easing: 'ease-out' },
- * });
- * ```
- */
-export const animate = (element: Element, config: AnimateOptions): Promise<void> => {
-  const { keyframes, options, commitStyles = true, respectReducedMotion = true, onFinish } = config;
-
-  if (respectReducedMotion && prefersReducedMotion()) {
-    if (commitStyles) {
-      applyFinalKeyframeStyles(element, keyframes);
-    }
-    onFinish?.();
-    return Promise.resolve();
-  }
-
-  const htmlElement = element as HTMLElement;
-  if (typeof htmlElement.animate !== 'function') {
-    if (commitStyles) {
-      applyFinalKeyframeStyles(element, keyframes);
-    }
-    onFinish?.();
-    return Promise.resolve();
-  }
-
-  return new Promise((resolve) => {
-    const animation = htmlElement.animate(keyframes, options);
-    let finalized = false;
-    const finalize = () => {
-      if (finalized) return;
-      finalized = true;
-      if (commitStyles) {
-        if (typeof animation.commitStyles === 'function') {
-          animation.commitStyles();
-        } else {
-          applyFinalKeyframeStyles(element, keyframes);
-        }
-      }
-      animation.cancel();
-      onFinish?.();
-      resolve();
-    };
-
-    animation.onfinish = finalize;
-    if (animation.finished) {
-      animation.finished.then(finalize).catch(finalize);
-    }
-  });
-};
+/**
+ * Web Animations helpers.
+ *
+ * @module bquery/motion
+ */
+
+import { prefersReducedMotion } from './reduced-motion';
+import type { AnimateOptions } from './types';
+
+/** @internal */
+const isStyleValue = (value: unknown): value is string | number =>
+  typeof value === 'string' || typeof value === 'number';
+
+/**
+ * Convert camelCase property names to kebab-case for CSS.
+ * @internal
+ */
+const toKebabCase = (str: string): string => {
+  return str.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+};
+
+/** @internal */
+export const applyFinalKeyframeStyles = (
+  element: Element,
+  keyframes: Keyframe[] | PropertyIndexedKeyframes
+): void => {
+  const htmlElement = element as HTMLElement;
+  const style = htmlElement.style;
+
+  if (Array.isArray(keyframes)) {
+    const last = keyframes[keyframes.length - 1];
+    if (!last) return;
+    for (const [prop, value] of Object.entries(last)) {
+      if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
+      if (isStyleValue(value)) {
+        // Convert camelCase to kebab-case for CSS properties
+        const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
+        style.setProperty(cssProp, String(value));
+      }
+    }
+    return;
+  }
+
+  for (const [prop, value] of Object.entries(keyframes)) {
+    if (prop === 'offset' || prop === 'easing' || prop === 'composite') continue;
+    const finalValue = Array.isArray(value) ? value[value.length - 1] : value;
+    if (isStyleValue(finalValue)) {
+      // Convert camelCase to kebab-case for CSS properties
+      const cssProp = prop.startsWith('--') ? prop : toKebabCase(prop);
+      style.setProperty(cssProp, String(finalValue));
+    }
+  }
+};
+
+/**
+ * Animate an element using the Web Animations API with reduced-motion fallback.
+ *
+ * @param element - Element to animate
+ * @param config - Animation configuration
+ * @returns Promise that resolves when animation completes
+ *
+ * @example
+ * ```ts
+ * await animate(element, {
+ *   keyframes: [{ opacity: 0 }, { opacity: 1 }],
+ *   options: { duration: 200, easing: 'ease-out' },
+ * });
+ * ```
+ */
+export const animate = (element: Element, config: AnimateOptions): Promise<void> => {
+  const { keyframes, options, commitStyles = true, respectReducedMotion = true, onFinish } = config;
+
+  if (respectReducedMotion && prefersReducedMotion()) {
+    if (commitStyles) {
+      applyFinalKeyframeStyles(element, keyframes);
+    }
+    onFinish?.();
+    return Promise.resolve();
+  }
+
+  const htmlElement = element as HTMLElement;
+  if (typeof htmlElement.animate !== 'function') {
+    if (commitStyles) {
+      applyFinalKeyframeStyles(element, keyframes);
+    }
+    onFinish?.();
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve) => {
+    const animation = htmlElement.animate(keyframes, options);
+    let finalized = false;
+    const finalize = () => {
+      if (finalized) return;
+      finalized = true;
+      if (commitStyles) {
+        if (typeof animation.commitStyles === 'function') {
+          animation.commitStyles();
+        } else {
+          applyFinalKeyframeStyles(element, keyframes);
+        }
+      }
+      animation.cancel();
+      onFinish?.();
+      resolve();
+    };
+
+    animation.onfinish = finalize;
+    if (animation.finished) {
+      animation.finished.then(finalize).catch(finalize);
+    }
+  });
+};