@bquery/bquery 1.0.0

package/dist/core/utils.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Utility helpers used across the framework.
+ * These are intentionally small and framework-agnostic to keep the core tiny.
+ *
+ * @module bquery/core/utils
+ */
+/**
+ * Utility object containing common helper functions.
+ * All utilities are designed to be tree-shakeable and have zero dependencies.
+ */
+export declare const utils: {
+    /**
+     * 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
+     *
+     * @example
+     * ```ts
+     * const original = { nested: { value: 1 } };
+     * const copy = utils.clone(original);
+     * copy.nested.value = 2;
+     * console.log(original.nested.value); // 1
+     * ```
+     */
+    clone<T>(value: T): T;
+    /**
+     * Deep-merges plain objects into a new object.
+     * Later sources override earlier ones for primitive values.
+     * Objects are recursively merged.
+     *
+     * @template T - The type of the merged object
+     * @param sources - Objects to merge
+     * @returns A new object with all sources merged
+     *
+     * @example
+     * ```ts
+     * const result = utils.merge(
+     *   { a: 1, nested: { x: 1 } },
+     *   { b: 2, nested: { y: 2 } }
+     * );
+     * // Result: { a: 1, b: 2, nested: { x: 1, y: 2 } }
+     * ```
+     */
+    merge<T extends Record<string, unknown>>(...sources: T[]): T;
+    /**
+     * 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 = utils.debounce((query: string) => {
+     *   console.log('Searching:', query);
+     * }, 300);
+     *
+     * search('h');
+     * search('he');
+     * search('hello'); // Only this call executes after 300ms
+     * ```
+     */
+    debounce<TArgs extends unknown[]>(fn: (...args: TArgs) => void, delayMs: number): (...args: TArgs) => void;
+    /**
+     * 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 = utils.throttle(() => {
+     *   console.log('Scroll position:', window.scrollY);
+     * }, 100);
+     *
+     * window.addEventListener('scroll', handleScroll);
+     * ```
+     */
+    throttle<TArgs extends unknown[]>(fn: (...args: TArgs) => void, intervalMs: number): (...args: TArgs) => void;
+    /**
+     * 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 = utils.uid('modal'); // 'modal_x7k2m9p'
+     * ```
+     */
+    uid(prefix?: string): string;
+    /**
+     * Checks if a value is a DOM Element.
+     *
+     * @param value - The value to check
+     * @returns True if the value is an Element
+     */
+    isElement(value: unknown): value is Element;
+    /**
+     * Checks if a value is a BQueryCollection-like object.
+     *
+     * @param value - The value to check
+     * @returns True if the value has an elements array property
+     */
+    isCollection(value: unknown): value is {
+        elements: Element[];
+    };
+    /**
+     * 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
+     * utils.isEmpty('');       // true
+     * utils.isEmpty([]);       // true
+     * utils.isEmpty({});       // true
+     * utils.isEmpty(null);     // true
+     * utils.isEmpty('hello');  // false
+     * utils.isEmpty([1, 2]);   // false
+     * ```
+     */
+    isEmpty(value: unknown): boolean;
+    /**
+     * 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
+     */
+    isPlainObject(value: unknown): value is Record<string, unknown>;
+    /**
+     * Checks if a value is a function.
+     *
+     * @param value - The value to check
+     * @returns True if the value is a function
+     */
+    isFunction(value: unknown): value is (...args: unknown[]) => unknown;
+    /**
+     * Checks if a value is a string.
+     *
+     * @param value - The value to check
+     * @returns True if the value is a string
+     */
+    isString(value: unknown): value is string;
+    /**
+     * Checks if a value is a number (excluding NaN).
+     *
+     * @param value - The value to check
+     * @returns True if the value is a valid number
+     */
+    isNumber(value: unknown): value is number;
+    /**
+     * Checks if a value is a boolean.
+     *
+     * @param value - The value to check
+     * @returns True if the value is a boolean
+     */
+    isBoolean(value: unknown): value is boolean;
+    /**
+     * Checks if a value is an array.
+     *
+     * @template T - The type of array elements
+     * @param value - The value to check
+     * @returns True if the value is an array
+     */
+    isArray<T = unknown>(value: unknown): value is T[];
+    /**
+     * 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
+     * utils.parseJson('{"name":"bQuery"}', {}); // { name: 'bQuery' }
+     * utils.parseJson('invalid', {}); // {}
+     * ```
+     */
+    parseJson<T>(json: string, fallback: T): T;
+    /**
+     * 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' };
+     * utils.pick(user, ['name', 'email']); // { name: 'John', email: 'john@example.com' }
+     * ```
+     */
+    pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+    /**
+     * 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' };
+     * utils.omit(user, ['password']); // { name: 'John', age: 30 }
+     * ```
+     */
+    omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+    /**
+     * Delays execution for a specified number of milliseconds.
+     *
+     * @param ms - Milliseconds to delay
+     * @returns A promise that resolves after the delay
+     *
+     * @example
+     * ```ts
+     * await utils.sleep(1000); // Wait 1 second
+     * console.log('Done!');
+     * ```
+     */
+    sleep(ms: number): Promise<void>;
+    /**
+     * 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 = utils.randomInt(1, 6); // Random dice roll
+     * ```
+     */
+    randomInt(min: number, max: number): number;
+    /**
+     * 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
+     * utils.clamp(150, 0, 100); // 100
+     * utils.clamp(-10, 0, 100); // 0
+     * utils.clamp(50, 0, 100);  // 50
+     * ```
+     */
+    clamp(value: number, min: number, max: number): number;
+    /**
+     * Capitalizes the first letter of a string.
+     *
+     * @param str - The string to capitalize
+     * @returns The capitalized string
+     *
+     * @example
+     * ```ts
+     * utils.capitalize('hello'); // 'Hello'
+     * ```
+     */
+    capitalize(str: string): string;
+    /**
+     * Converts a string to kebab-case.
+     *
+     * @param str - The string to convert
+     * @returns The kebab-cased string
+     *
+     * @example
+     * ```ts
+     * utils.toKebabCase('myVariableName'); // 'my-variable-name'
+     * ```
+     */
+    toKebabCase(str: string): string;
+    /**
+     * Converts a string to camelCase.
+     *
+     * @param str - The string to convert
+     * @returns The camelCased string
+     *
+     * @example
+     * ```ts
+     * utils.toCamelCase('my-variable-name'); // 'myVariableName'
+     * ```
+     */
+    toCamelCase(str: string): string;
+};
+//# sourceMappingURL=utils.d.ts.map

package/dist/core/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/core/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;;;;;;;;;OAcG;UACG,CAAC,SAAS,CAAC,GAAG,CAAC;IAOrB;;;;;;;;;;;;;;;;;OAiBG;UACG,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,EAAE,GAAG,CAAC;IAiB5D;;;;;;;;;;;;;;;;;;;OAmBG;aACM,KAAK,SAAS,OAAO,EAAE,MAC1B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,WACnB,MAAM,GACd,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI;IAU3B;;;;;;;;;;;;;;;;OAgBG;aACM,KAAK,SAAS,OAAO,EAAE,MAC1B,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,cAChB,MAAM,GACjB,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI;IAW3B;;;;;;;;;;OAUG;0BACqB,MAAM;IAI9B;;;;;OAKG;qBACc,OAAO,GAAG,KAAK,IAAI,OAAO;IAI3C;;;;;OAKG;wBACiB,OAAO,GAAG,KAAK,IAAI;QAAE,QAAQ,EAAE,OAAO,EAAE,CAAA;KAAE;IAI9D;;;;;;;;;;;;;;;OAeG;mBACY,OAAO,GAAG,OAAO;IAQhC;;;;;OAKG;yBACkB,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI/D;;;;;OAKG;sBACe,OAAO,GAAG,KAAK,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO;IAIpE;;;;;OAKG;oBACa,OAAO,GAAG,KAAK,IAAI,MAAM;IAIzC;;;;;OAKG;oBACa,OAAO,GAAG,KAAK,IAAI,MAAM;IAIzC;;;;;OAKG;qBACc,OAAO,GAAG,KAAK,IAAI,OAAO;IAI3C;;;;;;OAMG;YACK,CAAC,mBAAmB,OAAO,GAAG,KAAK,IAAI,CAAC,EAAE;IAIlD;;;;;;;;;;;;;OAaG;cACO,CAAC,QAAQ,MAAM,YAAY,CAAC,GAAG,CAAC;IAQ1C;;;;;;;;;;;;;;OAcG;SACE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IAUzF;;;;;;;;;;;;;;OAcG;SACE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;IAQzF;;;;;;;;;;;OAWG;cACO,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC;;;;;;;;;;;OAWG;mBACY,MAAM,OAAO,MAAM,GAAG,MAAM;IAI3C;;;;;;;;;;;;;;OAcG;iBACU,MAAM,OAAO,MAAM,OAAO,MAAM,GAAG,MAAM;IAItD;;;;;;;;;;OAUG;oBACa,MAAM,GAAG,MAAM;IAK/B;;;;;;;;;;OAUG;qBACc,MAAM,GAAG,MAAM;IAOhC;;;;;;;;;;OAUG;qBACc,MAAM,GAAG,MAAM;CAKjC,CAAC"}