@mohasinac/utils 0.1.0 → 1.1.0

package/dist/index.d.cts

@@ -19,6 +19,7 @@ declare function nowMs(): number;
 declare function isSameMonth(a: Date | number, b: Date | number): boolean;
 declare function currentYear(): string;
 declare function nowISO(): string;
+declare function formatCustomDate(date: Date | string, format?: "short" | "medium" | "long" | "full"): string;
 
 /**
  * Number Formatting Utilities
@@ -160,4 +161,193 @@ interface GeneratePayoutIdInput {
 }
 declare function generatePayoutId(input: GeneratePayoutIdInput): string;
 
-export { type GenerateAuctionIdInput, type GenerateBidIdInput, type GenerateBlogPostIdInput, type GenerateCarouselIdInput, type GenerateCategoryIdInput, type GenerateFAQIdInput, type GenerateHomepageSectionIdInput, type GenerateOrderIdInput, type GeneratePayoutIdInput, type GeneratePreOrderIdInput, type GenerateProductIdInput, type GenerateReviewIdInput, type GenerateUserIdInput, arrayToObject, booleanToString, capitalize, capitalizeWords, currentYear, dateToISOString, deleteCookie, escapeHtml, firestoreTimestampToDate, formatCompactNumber, formatCurrency, formatDate, formatDateRange, formatDateTime, formatDecimal, formatFileSize, formatMonthYear, formatNumber, formatOrdinal, formatPercentage, formatRelativeTime, formatTime, generateAuctionId, generateBidId, generateBlogPostId, generateCarouselId, generateCategoryId, generateCouponId, generateFAQId, generateHomepageSectionId, generateOrderId, generatePayoutId, generatePreOrderId, generateProductId, generateReviewId, generateUserId, getCookie, hasCookie, isEmptyString, isFuture, isPast, isSameMonth, isToday, maskString, nowISO, nowMs, objectToArray, objectToQueryString, parseCookies, parseFormattedNumber, proseMirrorToHtml, queryStringToObject, randomString, resolveDate, slugify, stringToBoolean, stripHtml, truncate, truncateWords };
+/**
+ * Array Data Helpers
+ *
+ * Generic helpers for array data operations — no external dependencies.
+ */
+declare function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
+declare function unique<T>(array: T[]): T[];
+declare function uniqueBy<T>(array: T[], key: keyof T): T[];
+declare function sortBy<T>(array: T[], key: keyof T, order?: "asc" | "desc"): T[];
+declare function chunk<T>(array: T[], size: number): T[][];
+declare function paginate<T>(array: T[], page: number, perPage: number): {
+    data: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+};
+
+/**
+ * Object Data Helpers
+ *
+ * Generic helpers for object data operations — no external dependencies.
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T;
+declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+declare function omit<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+declare function isEmptyObject(obj: Record<string, any>): boolean;
+declare function deepClone<T>(obj: T): T;
+declare function isEqual(obj1: any, obj2: any): boolean;
+declare function cleanObject<T extends Record<string, any>>(obj: T, options?: {
+    removeEmpty?: boolean;
+    removeNull?: boolean;
+    removeUndefined?: boolean;
+}): Partial<T>;
+
+/**
+ * Pagination Helper
+ *
+ * Generic helpers for pagination metadata calculations.
+ */
+interface PaginationOptions {
+    page: number;
+    perPage: number;
+    total: number;
+}
+interface PaginationResult {
+    currentPage: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    nextPage: number | null;
+    prevPage: number | null;
+    startIndex: number;
+    endIndex: number;
+}
+declare function calculatePagination(options: PaginationOptions): PaginationResult;
+
+/**
+ * Sorting Helper
+ *
+ * Generic helpers for sorting operations.
+ */
+type SortOrder = "asc" | "desc";
+declare function sort<T>(array: T[], key: keyof T, order?: SortOrder): T[];
+
+/**
+ * Filter Helper
+ *
+ * Builds Sieve-compatible filter strings from conditional entries.
+ *
+ * @example
+ * ```ts
+ * buildSieveFilters(
+ *   ["status==", statusFilter],
+ *   ["totalPrice>=", minAmount],
+ *   ["title@=*", searchTerm],
+ * );
+ * // → "status==pending,totalPrice>=100,title@=*shoes"
+ * ```
+ */
+type FilterEntry = [expression: string, value: string | undefined | null];
+declare function buildSieveFilters(...entries: FilterEntry[]): string;
+
+/**
+ * Animation Helpers
+ *
+ * Pure easing functions for JavaScript animations and transitions.
+ * All functions accept a normalized time value `t` in [0, 1]
+ * and return a value in [0, 1].
+ */
+declare const easings: {
+    linear: (t: number) => number;
+    easeInQuad: (t: number) => number;
+    easeOutQuad: (t: number) => number;
+    easeInOutQuad: (t: number) => number;
+    easeInCubic: (t: number) => number;
+    easeOutCubic: (t: number) => number;
+    easeInOutCubic: (t: number) => number;
+    easeInQuart: (t: number) => number;
+    easeOutQuart: (t: number) => number;
+    easeInOutQuart: (t: number) => number;
+};
+
+/**
+ * Color Helpers
+ *
+ * Pure utility functions for color manipulation and conversion.
+ */
+/**
+ * Converts a hexadecimal color to RGB values.
+ *
+ * @param hex - The hex color string (with or without '#')
+ * @returns An object with r, g, b values, or null if invalid
+ */
+declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Converts RGB values to a hexadecimal color string.
+ *
+ * @param r - Red value (0-255)
+ * @param g - Green value (0-255)
+ * @param b - Blue value (0-255)
+ * @returns The hex color string with '#' prefix
+ */
+declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ * Determines the best contrasting text color (black or white) for a given background.
+ *
+ * @param hex - The background hex color
+ * @returns '#000000' for light backgrounds, '#ffffff' for dark backgrounds
+ */
+declare function getContrastColor(hex: string): "#000000" | "#ffffff";
+
+/**
+ * Event Manager Utilities
+ *
+ * Centralized DOM event handler management, throttle/debounce,
+ * and viewport / scroll / body-scroll utilities.
+ */
+declare class GlobalEventManager {
+    private handlers;
+    private handlerIds;
+    private generateId;
+    private getTargetId;
+    add(target: EventTarget, type: string, callback: EventListener, options?: AddEventListenerOptions): string;
+    remove(id: string): void;
+    removeAllForTarget(target: EventTarget, type?: string): void;
+    clear(): void;
+    getHandlerCount(): number;
+    has(id: string): boolean;
+}
+declare const globalEventManager: GlobalEventManager;
+declare function throttle<T extends (...args: any[]) => any>(func: T, delay: number): (...args: Parameters<T>) => void;
+declare function debounce<T extends (...args: any[]) => any>(func: T, delay: number): (...args: Parameters<T>) => void;
+declare function addGlobalScrollHandler(callback: (event: Event) => void, options?: {
+    throttle?: number;
+    target?: EventTarget;
+}): string;
+declare function addGlobalResizeHandler(callback: (event: Event) => void, options?: {
+    throttle?: number;
+}): string;
+declare function addGlobalClickHandler(selector: string, callback: (event: MouseEvent, element: Element) => void, options?: {
+    preventDefault?: boolean;
+}): string;
+declare function addGlobalKeyHandler(key: string | string[], callback: (event: KeyboardEvent) => void, options?: {
+    preventDefault?: boolean;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+}): string;
+declare function removeGlobalHandler(id: string): void;
+declare function isMobileDevice(): boolean;
+declare function hasTouchSupport(): boolean;
+declare function getViewportDimensions(): {
+    width: number;
+    height: number;
+};
+declare function isInViewport(element: HTMLElement, offset?: number): boolean;
+declare function smoothScrollTo(element: HTMLElement | string, options?: {
+    offset?: number;
+}): void;
+declare function preventBodyScroll(prevent: boolean): void;
+
+export { type GenerateAuctionIdInput, type GenerateBidIdInput, type GenerateBlogPostIdInput, type GenerateCarouselIdInput, type GenerateCategoryIdInput, type GenerateFAQIdInput, type GenerateHomepageSectionIdInput, type GenerateOrderIdInput, type GeneratePayoutIdInput, type GeneratePreOrderIdInput, type GenerateProductIdInput, type GenerateReviewIdInput, type GenerateUserIdInput, GlobalEventManager, type PaginationOptions, type PaginationResult, type SortOrder, addGlobalClickHandler, addGlobalKeyHandler, addGlobalResizeHandler, addGlobalScrollHandler, arrayToObject, booleanToString, buildSieveFilters, calculatePagination, capitalize, capitalizeWords, chunk, cleanObject, currentYear, dateToISOString, debounce, deepClone, deepMerge, deleteCookie, easings, escapeHtml, firestoreTimestampToDate, formatCompactNumber, formatCurrency, formatCustomDate, formatDate, formatDateRange, formatDateTime, formatDecimal, formatFileSize, formatMonthYear, formatNumber, formatOrdinal, formatPercentage, formatRelativeTime, formatTime, generateAuctionId, generateBidId, generateBlogPostId, generateCarouselId, generateCategoryId, generateCouponId, generateFAQId, generateHomepageSectionId, generateOrderId, generatePayoutId, generatePreOrderId, generateProductId, generateReviewId, generateUserId, getContrastColor, getCookie, getViewportDimensions, globalEventManager, groupBy, hasCookie, hasTouchSupport, hexToRgb, isEmptyObject, isEmptyString, isEqual, isFuture, isInViewport, isMobileDevice, isPast, isSameMonth, isToday, maskString, nowISO, nowMs, objectToArray, objectToQueryString, omit, paginate, parseCookies, parseFormattedNumber, pick, preventBodyScroll, proseMirrorToHtml, queryStringToObject, randomString, removeGlobalHandler, resolveDate, rgbToHex, slugify, smoothScrollTo, sort, sortBy, stringToBoolean, stripHtml, throttle, truncate, truncateWords, unique, uniqueBy };

package/dist/index.d.ts

@@ -19,6 +19,7 @@ declare function nowMs(): number;
 declare function isSameMonth(a: Date | number, b: Date | number): boolean;
 declare function currentYear(): string;
 declare function nowISO(): string;
+declare function formatCustomDate(date: Date | string, format?: "short" | "medium" | "long" | "full"): string;
 
 /**
  * Number Formatting Utilities
@@ -160,4 +161,193 @@ interface GeneratePayoutIdInput {
 }
 declare function generatePayoutId(input: GeneratePayoutIdInput): string;
 
-export { type GenerateAuctionIdInput, type GenerateBidIdInput, type GenerateBlogPostIdInput, type GenerateCarouselIdInput, type GenerateCategoryIdInput, type GenerateFAQIdInput, type GenerateHomepageSectionIdInput, type GenerateOrderIdInput, type GeneratePayoutIdInput, type GeneratePreOrderIdInput, type GenerateProductIdInput, type GenerateReviewIdInput, type GenerateUserIdInput, arrayToObject, booleanToString, capitalize, capitalizeWords, currentYear, dateToISOString, deleteCookie, escapeHtml, firestoreTimestampToDate, formatCompactNumber, formatCurrency, formatDate, formatDateRange, formatDateTime, formatDecimal, formatFileSize, formatMonthYear, formatNumber, formatOrdinal, formatPercentage, formatRelativeTime, formatTime, generateAuctionId, generateBidId, generateBlogPostId, generateCarouselId, generateCategoryId, generateCouponId, generateFAQId, generateHomepageSectionId, generateOrderId, generatePayoutId, generatePreOrderId, generateProductId, generateReviewId, generateUserId, getCookie, hasCookie, isEmptyString, isFuture, isPast, isSameMonth, isToday, maskString, nowISO, nowMs, objectToArray, objectToQueryString, parseCookies, parseFormattedNumber, proseMirrorToHtml, queryStringToObject, randomString, resolveDate, slugify, stringToBoolean, stripHtml, truncate, truncateWords };
+/**
+ * Array Data Helpers
+ *
+ * Generic helpers for array data operations — no external dependencies.
+ */
+declare function groupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
+declare function unique<T>(array: T[]): T[];
+declare function uniqueBy<T>(array: T[], key: keyof T): T[];
+declare function sortBy<T>(array: T[], key: keyof T, order?: "asc" | "desc"): T[];
+declare function chunk<T>(array: T[], size: number): T[][];
+declare function paginate<T>(array: T[], page: number, perPage: number): {
+    data: T[];
+    total: number;
+    page: number;
+    perPage: number;
+    totalPages: number;
+};
+
+/**
+ * Object Data Helpers
+ *
+ * Generic helpers for object data operations — no external dependencies.
+ */
+declare function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T;
+declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+declare function omit<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+declare function isEmptyObject(obj: Record<string, any>): boolean;
+declare function deepClone<T>(obj: T): T;
+declare function isEqual(obj1: any, obj2: any): boolean;
+declare function cleanObject<T extends Record<string, any>>(obj: T, options?: {
+    removeEmpty?: boolean;
+    removeNull?: boolean;
+    removeUndefined?: boolean;
+}): Partial<T>;
+
+/**
+ * Pagination Helper
+ *
+ * Generic helpers for pagination metadata calculations.
+ */
+interface PaginationOptions {
+    page: number;
+    perPage: number;
+    total: number;
+}
+interface PaginationResult {
+    currentPage: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    nextPage: number | null;
+    prevPage: number | null;
+    startIndex: number;
+    endIndex: number;
+}
+declare function calculatePagination(options: PaginationOptions): PaginationResult;
+
+/**
+ * Sorting Helper
+ *
+ * Generic helpers for sorting operations.
+ */
+type SortOrder = "asc" | "desc";
+declare function sort<T>(array: T[], key: keyof T, order?: SortOrder): T[];
+
+/**
+ * Filter Helper
+ *
+ * Builds Sieve-compatible filter strings from conditional entries.
+ *
+ * @example
+ * ```ts
+ * buildSieveFilters(
+ *   ["status==", statusFilter],
+ *   ["totalPrice>=", minAmount],
+ *   ["title@=*", searchTerm],
+ * );
+ * // → "status==pending,totalPrice>=100,title@=*shoes"
+ * ```
+ */
+type FilterEntry = [expression: string, value: string | undefined | null];
+declare function buildSieveFilters(...entries: FilterEntry[]): string;
+
+/**
+ * Animation Helpers
+ *
+ * Pure easing functions for JavaScript animations and transitions.
+ * All functions accept a normalized time value `t` in [0, 1]
+ * and return a value in [0, 1].
+ */
+declare const easings: {
+    linear: (t: number) => number;
+    easeInQuad: (t: number) => number;
+    easeOutQuad: (t: number) => number;
+    easeInOutQuad: (t: number) => number;
+    easeInCubic: (t: number) => number;
+    easeOutCubic: (t: number) => number;
+    easeInOutCubic: (t: number) => number;
+    easeInQuart: (t: number) => number;
+    easeOutQuart: (t: number) => number;
+    easeInOutQuart: (t: number) => number;
+};
+
+/**
+ * Color Helpers
+ *
+ * Pure utility functions for color manipulation and conversion.
+ */
+/**
+ * Converts a hexadecimal color to RGB values.
+ *
+ * @param hex - The hex color string (with or without '#')
+ * @returns An object with r, g, b values, or null if invalid
+ */
+declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+/**
+ * Converts RGB values to a hexadecimal color string.
+ *
+ * @param r - Red value (0-255)
+ * @param g - Green value (0-255)
+ * @param b - Blue value (0-255)
+ * @returns The hex color string with '#' prefix
+ */
+declare function rgbToHex(r: number, g: number, b: number): string;
+/**
+ * Determines the best contrasting text color (black or white) for a given background.
+ *
+ * @param hex - The background hex color
+ * @returns '#000000' for light backgrounds, '#ffffff' for dark backgrounds
+ */
+declare function getContrastColor(hex: string): "#000000" | "#ffffff";
+
+/**
+ * Event Manager Utilities
+ *
+ * Centralized DOM event handler management, throttle/debounce,
+ * and viewport / scroll / body-scroll utilities.
+ */
+declare class GlobalEventManager {
+    private handlers;
+    private handlerIds;
+    private generateId;
+    private getTargetId;
+    add(target: EventTarget, type: string, callback: EventListener, options?: AddEventListenerOptions): string;
+    remove(id: string): void;
+    removeAllForTarget(target: EventTarget, type?: string): void;
+    clear(): void;
+    getHandlerCount(): number;
+    has(id: string): boolean;
+}
+declare const globalEventManager: GlobalEventManager;
+declare function throttle<T extends (...args: any[]) => any>(func: T, delay: number): (...args: Parameters<T>) => void;
+declare function debounce<T extends (...args: any[]) => any>(func: T, delay: number): (...args: Parameters<T>) => void;
+declare function addGlobalScrollHandler(callback: (event: Event) => void, options?: {
+    throttle?: number;
+    target?: EventTarget;
+}): string;
+declare function addGlobalResizeHandler(callback: (event: Event) => void, options?: {
+    throttle?: number;
+}): string;
+declare function addGlobalClickHandler(selector: string, callback: (event: MouseEvent, element: Element) => void, options?: {
+    preventDefault?: boolean;
+}): string;
+declare function addGlobalKeyHandler(key: string | string[], callback: (event: KeyboardEvent) => void, options?: {
+    preventDefault?: boolean;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+}): string;
+declare function removeGlobalHandler(id: string): void;
+declare function isMobileDevice(): boolean;
+declare function hasTouchSupport(): boolean;
+declare function getViewportDimensions(): {
+    width: number;
+    height: number;
+};
+declare function isInViewport(element: HTMLElement, offset?: number): boolean;
+declare function smoothScrollTo(element: HTMLElement | string, options?: {
+    offset?: number;
+}): void;
+declare function preventBodyScroll(prevent: boolean): void;
+
+export { type GenerateAuctionIdInput, type GenerateBidIdInput, type GenerateBlogPostIdInput, type GenerateCarouselIdInput, type GenerateCategoryIdInput, type GenerateFAQIdInput, type GenerateHomepageSectionIdInput, type GenerateOrderIdInput, type GeneratePayoutIdInput, type GeneratePreOrderIdInput, type GenerateProductIdInput, type GenerateReviewIdInput, type GenerateUserIdInput, GlobalEventManager, type PaginationOptions, type PaginationResult, type SortOrder, addGlobalClickHandler, addGlobalKeyHandler, addGlobalResizeHandler, addGlobalScrollHandler, arrayToObject, booleanToString, buildSieveFilters, calculatePagination, capitalize, capitalizeWords, chunk, cleanObject, currentYear, dateToISOString, debounce, deepClone, deepMerge, deleteCookie, easings, escapeHtml, firestoreTimestampToDate, formatCompactNumber, formatCurrency, formatCustomDate, formatDate, formatDateRange, formatDateTime, formatDecimal, formatFileSize, formatMonthYear, formatNumber, formatOrdinal, formatPercentage, formatRelativeTime, formatTime, generateAuctionId, generateBidId, generateBlogPostId, generateCarouselId, generateCategoryId, generateCouponId, generateFAQId, generateHomepageSectionId, generateOrderId, generatePayoutId, generatePreOrderId, generateProductId, generateReviewId, generateUserId, getContrastColor, getCookie, getViewportDimensions, globalEventManager, groupBy, hasCookie, hasTouchSupport, hexToRgb, isEmptyObject, isEmptyString, isEqual, isFuture, isInViewport, isMobileDevice, isPast, isSameMonth, isToday, maskString, nowISO, nowMs, objectToArray, objectToQueryString, omit, paginate, parseCookies, parseFormattedNumber, pick, preventBodyScroll, proseMirrorToHtml, queryStringToObject, randomString, removeGlobalHandler, resolveDate, rgbToHex, slugify, smoothScrollTo, sort, sortBy, stringToBoolean, stripHtml, throttle, truncate, truncateWords, unique, uniqueBy };