@od-oneapp/utils 2026.2.2001-canary.1

package/README.md

@@ -0,0 +1,29 @@
+# @od-oneapp/utils
+
+Collection of framework-agnostic utilities (class name helpers, formatting, validation, rate limiting) shared across
+OneApp workspaces. Functions ship as TypeScript source and include rich JSDoc examples to improve AI tooling
+performance.
+
+## Installation
+
+```bash
+pnpm --filter= @od-oneapp/utils < workspace > add
+```
+
+## Usage
+
+```ts
+import { cn, debounce, formatDate, truncate } from "@od-oneapp/utils";
+
+const className = cn("base", isActive && "active");
+const save = debounce((payload: unknown) => console.log(payload), 300);
+const label = truncate(formatDate(new Date()), 12);
+```
+
+## Development
+
+- `pnpm --filter=@od-oneapp/utils lint`
+- `pnpm --filter=@od-oneapp/utils typecheck`
+
+Because utilities are exported as ESM TypeScript, ensure your runtime transpiles them (e.g., via Next.js
+`transpilePackages`).

package/cn.d.mts

@@ -0,0 +1,7 @@
+import { ClassValue } from "clsx";
+
+//#region src/cn.d.ts
+declare function cn(...inputs: ClassValue[]): string;
+//#endregion
+export { cn };
+//# sourceMappingURL=cn.d.mts.map

package/cn.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.d.mts","names":[],"sources":["../src/cn.ts"],"mappings":";;;iBAmCgB,EAAA,CAAA,GAAM,MAAA,EAAQ,UAAA"}

package/cn.mjs

@@ -0,0 +1,42 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+//#region src/cn.ts
+/**
+* @fileoverview Utility for merging class names with Tailwind CSS conflict resolution.
+*
+* Uses clsx for conditional class handling and tailwind-merge for resolving
+* Tailwind CSS class conflicts (e.g., 'px-2 px-4' becomes 'px-4').
+*
+* @module @od-oneapp/utils/cn
+*/
+/**
+* Merges class names with Tailwind CSS conflict resolution.
+*
+* @param inputs - Variable number of class name arguments (strings, arrays, objects, or conditionals)
+* @returns Merged class names string with Tailwind conflicts resolved
+*
+* @example
+* ```ts
+* // Basic usage: merge class strings with conflict resolution
+* cn('px-2 py-1', 'px-4') // Output: 'py-1 px-4' (px-4 wins)
+*
+* // Conditional classes: falsy values are filtered out
+* cn('base', isActive && 'active') // Output: 'base active' or 'base'
+*
+* // Object syntax: keys with truthy values are included
+* cn('base', { active: isActive }) // Output: 'base active' or 'base'
+*
+* // Mixed usage: all patterns can be combined
+* cn('btn', 'btn-primary', isDisabled && 'opacity-50', { 'cursor-not-allowed': isDisabled })
+* // Output: 'btn btn-primary opacity-50 cursor-not-allowed' (if disabled)
+* // Output: 'btn btn-primary' (if enabled)
+* ```
+*/
+function cn(...inputs) {
+	return twMerge(clsx(inputs));
+}
+
+//#endregion
+export { cn };
+//# sourceMappingURL=cn.mjs.map

package/cn.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cn.mjs","names":[],"sources":["../src/cn.ts"],"sourcesContent":["/**\n * @fileoverview Utility for merging class names with Tailwind CSS conflict resolution.\n *\n * Uses clsx for conditional class handling and tailwind-merge for resolving\n * Tailwind CSS class conflicts (e.g., 'px-2 px-4' becomes 'px-4').\n *\n * @module @od-oneapp/utils/cn\n */\n\nimport { clsx, type ClassValue } from 'clsx';\nimport { twMerge } from 'tailwind-merge';\n\n/**\n * Merges class names with Tailwind CSS conflict resolution.\n *\n * @param inputs - Variable number of class name arguments (strings, arrays, objects, or conditionals)\n * @returns Merged class names string with Tailwind conflicts resolved\n *\n * @example\n * ```ts\n * // Basic usage: merge class strings with conflict resolution\n * cn('px-2 py-1', 'px-4') // Output: 'py-1 px-4' (px-4 wins)\n *\n * // Conditional classes: falsy values are filtered out\n * cn('base', isActive && 'active') // Output: 'base active' or 'base'\n *\n * // Object syntax: keys with truthy values are included\n * cn('base', { active: isActive }) // Output: 'base active' or 'base'\n *\n * // Mixed usage: all patterns can be combined\n * cn('btn', 'btn-primary', isDisabled && 'opacity-50', { 'cursor-not-allowed': isDisabled })\n * // Output: 'btn btn-primary opacity-50 cursor-not-allowed' (if disabled)\n * // Output: 'btn btn-primary' (if enabled)\n * ```\n */\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(clsx(inputs));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,SAAgB,GAAG,GAAG,QAA8B;AAClD,QAAO,QAAQ,KAAK,OAAO,CAAC"}

package/date.d.mts

@@ -0,0 +1,5 @@
+//#region src/date.d.ts
+declare function formatRelativeDate(date: Date | string | number, baseDate?: Date): string;
+//#endregion
+export { formatRelativeDate };
+//# sourceMappingURL=date.d.mts.map

package/date.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.d.mts","names":[],"sources":["../src/date.ts"],"mappings":";iBAqBgB,kBAAA,CACd,IAAA,EAAM,IAAA,oBACN,QAAA,GAAU,IAAA"}

package/date.mjs

@@ -0,0 +1,48 @@
+//#region src/date.ts
+/**
+* @fileoverview Date formatting utilities
+*
+* Provides date formatting functions for consistent date display across the codebase.
+*
+* @module @od-oneapp/utils/date
+*/
+/**
+* Format a date as a relative time string (e.g., "2 hours ago", "yesterday")
+*
+* @param date - The date to format
+* @param baseDate - The base date to compare against (defaults to now)
+* @returns A human-readable relative time string
+*
+* @example
+* ```ts
+* formatRelativeDate(new Date(Date.now() - 3600000)); // "1 hour ago"
+* formatRelativeDate(new Date(Date.now() - 86400000)); // "yesterday"
+* ```
+*/
+function formatRelativeDate(date, baseDate = /* @__PURE__ */ new Date()) {
+	const d = date instanceof Date ? date : new Date(date);
+	const diffMs = baseDate.getTime() - d.getTime();
+	const diffSeconds = Math.floor(diffMs / 1e3);
+	const diffMinutes = Math.floor(diffSeconds / 60);
+	const diffHours = Math.floor(diffMinutes / 60);
+	const diffDays = Math.floor(diffHours / 24);
+	if (diffSeconds < 60) return "just now";
+	if (diffMinutes < 60) return diffMinutes === 1 ? "1 minute ago" : `${diffMinutes} minutes ago`;
+	if (diffHours < 24) return diffHours === 1 ? "1 hour ago" : `${diffHours} hours ago`;
+	if (diffDays === 1) return "yesterday";
+	if (diffDays < 7) return `${diffDays} days ago`;
+	if (diffDays < 30) {
+		const weeks = Math.floor(diffDays / 7);
+		return weeks === 1 ? "1 week ago" : `${weeks} weeks ago`;
+	}
+	if (diffDays < 365) {
+		const months = Math.floor(diffDays / 30);
+		return months === 1 ? "1 month ago" : `${months} months ago`;
+	}
+	const years = Math.floor(diffDays / 365);
+	return years === 1 ? "1 year ago" : `${years} years ago`;
+}
+
+//#endregion
+export { formatRelativeDate };
+//# sourceMappingURL=date.mjs.map

package/date.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"date.mjs","names":[],"sources":["../src/date.ts"],"sourcesContent":["/**\n * @fileoverview Date formatting utilities\n *\n * Provides date formatting functions for consistent date display across the codebase.\n *\n * @module @od-oneapp/utils/date\n */\n\n/**\n * Format a date as a relative time string (e.g., \"2 hours ago\", \"yesterday\")\n *\n * @param date - The date to format\n * @param baseDate - The base date to compare against (defaults to now)\n * @returns A human-readable relative time string\n *\n * @example\n * ```ts\n * formatRelativeDate(new Date(Date.now() - 3600000)); // \"1 hour ago\"\n * formatRelativeDate(new Date(Date.now() - 86400000)); // \"yesterday\"\n * ```\n */\nexport function formatRelativeDate(\n  date: Date | string | number,\n  baseDate: Date = new Date(),\n): string {\n  const d = date instanceof Date ? date : new Date(date);\n  const now = baseDate;\n  const diffMs = now.getTime() - d.getTime();\n  const diffSeconds = Math.floor(diffMs / 1000);\n  const diffMinutes = Math.floor(diffSeconds / 60);\n  const diffHours = Math.floor(diffMinutes / 60);\n  const diffDays = Math.floor(diffHours / 24);\n\n  if (diffSeconds < 60) {\n    return 'just now';\n  }\n\n  if (diffMinutes < 60) {\n    return diffMinutes === 1 ? '1 minute ago' : `${diffMinutes} minutes ago`;\n  }\n\n  if (diffHours < 24) {\n    return diffHours === 1 ? '1 hour ago' : `${diffHours} hours ago`;\n  }\n\n  if (diffDays === 1) {\n    return 'yesterday';\n  }\n\n  if (diffDays < 7) {\n    return `${diffDays} days ago`;\n  }\n\n  if (diffDays < 30) {\n    const weeks = Math.floor(diffDays / 7);\n    return weeks === 1 ? '1 week ago' : `${weeks} weeks ago`;\n  }\n\n  if (diffDays < 365) {\n    const months = Math.floor(diffDays / 30);\n    return months === 1 ? '1 month ago' : `${months} months ago`;\n  }\n\n  const years = Math.floor(diffDays / 365);\n  return years === 1 ? '1 year ago' : `${years} years ago`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,mBACd,MACA,2BAAiB,IAAI,MAAM,EACnB;CACR,MAAM,IAAI,gBAAgB,OAAO,OAAO,IAAI,KAAK,KAAK;CAEtD,MAAM,SADM,SACO,SAAS,GAAG,EAAE,SAAS;CAC1C,MAAM,cAAc,KAAK,MAAM,SAAS,IAAK;CAC7C,MAAM,cAAc,KAAK,MAAM,cAAc,GAAG;CAChD,MAAM,YAAY,KAAK,MAAM,cAAc,GAAG;CAC9C,MAAM,WAAW,KAAK,MAAM,YAAY,GAAG;AAE3C,KAAI,cAAc,GAChB,QAAO;AAGT,KAAI,cAAc,GAChB,QAAO,gBAAgB,IAAI,iBAAiB,GAAG,YAAY;AAG7D,KAAI,YAAY,GACd,QAAO,cAAc,IAAI,eAAe,GAAG,UAAU;AAGvD,KAAI,aAAa,EACf,QAAO;AAGT,KAAI,WAAW,EACb,QAAO,GAAG,SAAS;AAGrB,KAAI,WAAW,IAAI;EACjB,MAAM,QAAQ,KAAK,MAAM,WAAW,EAAE;AACtC,SAAO,UAAU,IAAI,eAAe,GAAG,MAAM;;AAG/C,KAAI,WAAW,KAAK;EAClB,MAAM,SAAS,KAAK,MAAM,WAAW,GAAG;AACxC,SAAO,WAAW,IAAI,gBAAgB,GAAG,OAAO;;CAGlD,MAAM,QAAQ,KAAK,MAAM,WAAW,IAAI;AACxC,QAAO,UAAU,IAAI,eAAe,GAAG,MAAM"}

package/debounce.d.mts

@@ -0,0 +1,6 @@
+//#region src/debounce.d.ts
+declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+declare function throttle<T extends (...args: unknown[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
+//#endregion
+export { debounce, throttle };
+//# sourceMappingURL=debounce.d.mts.map

package/debounce.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.mts","names":[],"sources":["../src/debounce.ts"],"mappings":";iBA8CgB,QAAA,eAAuB,IAAA,wBAAA,CACrC,EAAA,EAAI,CAAA,EACJ,KAAA,eACK,IAAA,EAAM,UAAA,CAAW,CAAA;AAAA,iBA2DR,QAAA,eAAuB,IAAA,wBAAA,CACrC,EAAA,EAAI,CAAA,EACJ,KAAA,eACK,IAAA,EAAM,UAAA,CAAW,CAAA"}

package/debounce.mjs

@@ -0,0 +1,110 @@
+//#region src/debounce.ts
+/**
+* @fileoverview Debounce and throttle utilities for function execution control.
+*
+* Provides debounce and throttle functions to limit how often functions can fire.
+* Useful for optimizing performance and improving user experience.
+*
+* @module @od-oneapp/utils/debounce
+*/
+/**
+* Debounce function to limit how often a function can fire.
+*
+* Why debounce:
+* - Reduces API calls for search inputs (wait for user to stop typing)
+* - Prevents excessive re-renders during rapid state updates
+* - Improves performance for expensive operations (e.g., filtering large datasets)
+* - Better UX: only process final value, not intermediate states
+*
+* Use debounce when: You want the final value after user stops an action
+* Use throttle when: You want periodic values during continuous action
+*
+* @param fn - Function to debounce
+* @param delay - Delay in milliseconds (typical: 150-500ms for UX)
+* @returns Debounced function
+*
+* @example
+* ```ts
+* // Search input: only search after user stops typing
+* const debouncedSearch = debounce((query: string) => {
+*   fetchResults(query);
+* }, 300);
+*
+* // Call sequence over 400ms:
+* debouncedSearch('a');      // 0ms: Timer starts
+* debouncedSearch('ab');     // 100ms: Timer resets
+* debouncedSearch('abc');    // 200ms: Timer resets
+* // At 500ms: fetchResults('abc') executes
+* // Result: Only 1 API call with final query
+*
+* // Window resize: recalculate layout after resize stops
+* const debouncedResize = debounce(() => {
+*   recalculateLayout();
+* }, 250);
+* window.addEventListener('resize', debouncedResize);
+* ```
+*/
+function debounce(fn, delay) {
+	let timeoutId = null;
+	return function debounced(...args) {
+		if (timeoutId !== null) clearTimeout(timeoutId);
+		timeoutId = setTimeout(() => {
+			fn(...args);
+			timeoutId = null;
+		}, delay);
+	};
+}
+/**
+* Throttle function to ensure a function is called at most once per time period.
+*
+* Why throttle:
+* - Limits execution frequency for continuous events (scroll, mousemove)
+* - Guarantees function fires at regular intervals during activity
+* - Better than debounce for real-time feedback (e.g., scroll position)
+* - Prevents performance degradation from high-frequency events
+*
+* Use throttle when: You want periodic updates during continuous action
+* Use debounce when: You only care about the final state after action stops
+*
+* @param fn - Function to throttle
+* @param limit - Minimum time in milliseconds between calls (typical: 100-250ms)
+* @returns Throttled function
+*
+* @example
+* ```ts
+* // Scroll position tracking: update every 100ms while scrolling
+* const throttledScroll = throttle(() => {
+*   const position = window.scrollY;
+*   updateScrollIndicator(position);
+* }, 100);
+* window.addEventListener('scroll', throttledScroll);
+* // Result: Updates 10x per second during scroll, not 100x
+*
+* // Mouse move tracking for drag operations
+* const throttledMouseMove = throttle((e: MouseEvent) => {
+*   updateDragPosition(e.clientX, e.clientY);
+* }, 16); // ~60fps
+* element.addEventListener('mousemove', throttledMouseMove);
+*
+* // API polling: check status every 5 seconds max
+* const throttledPoll = throttle(() => {
+*   checkStatus();
+* }, 5000);
+* ```
+*/
+function throttle(fn, limit) {
+	let inThrottle = false;
+	return function throttled(...args) {
+		if (!inThrottle) {
+			fn(...args);
+			inThrottle = true;
+			setTimeout(() => {
+				inThrottle = false;
+			}, limit);
+		}
+	};
+}
+
+//#endregion
+export { debounce, throttle };
+//# sourceMappingURL=debounce.mjs.map

package/debounce.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.mjs","names":[],"sources":["../src/debounce.ts"],"sourcesContent":["/**\n * @fileoverview Debounce and throttle utilities for function execution control.\n *\n * Provides debounce and throttle functions to limit how often functions can fire.\n * Useful for optimizing performance and improving user experience.\n *\n * @module @od-oneapp/utils/debounce\n */\n\n/**\n * Debounce function to limit how often a function can fire.\n *\n * Why debounce:\n * - Reduces API calls for search inputs (wait for user to stop typing)\n * - Prevents excessive re-renders during rapid state updates\n * - Improves performance for expensive operations (e.g., filtering large datasets)\n * - Better UX: only process final value, not intermediate states\n *\n * Use debounce when: You want the final value after user stops an action\n * Use throttle when: You want periodic values during continuous action\n *\n * @param fn - Function to debounce\n * @param delay - Delay in milliseconds (typical: 150-500ms for UX)\n * @returns Debounced function\n *\n * @example\n * ```ts\n * // Search input: only search after user stops typing\n * const debouncedSearch = debounce((query: string) => {\n *   fetchResults(query);\n * }, 300);\n *\n * // Call sequence over 400ms:\n * debouncedSearch('a');      // 0ms: Timer starts\n * debouncedSearch('ab');     // 100ms: Timer resets\n * debouncedSearch('abc');    // 200ms: Timer resets\n * // At 500ms: fetchResults('abc') executes\n * // Result: Only 1 API call with final query\n *\n * // Window resize: recalculate layout after resize stops\n * const debouncedResize = debounce(() => {\n *   recalculateLayout();\n * }, 250);\n * window.addEventListener('resize', debouncedResize);\n * ```\n */\nexport function debounce<T extends (...args: unknown[]) => unknown>(\n  fn: T,\n  delay: number,\n): (...args: Parameters<T>) => void {\n  // Store timeout ID to cancel pending executions\n  // Using ReturnType<typeof setTimeout> for cross-platform compatibility (Node.js vs Browser)\n  let timeoutId: ReturnType<typeof setTimeout> | null = null;\n\n  return function debounced(...args: Parameters<T>) {\n    // Cancel previous timeout if exists\n    // This is the key behavior: each call resets the timer\n    if (timeoutId !== null) {\n      clearTimeout(timeoutId);\n    }\n\n    // Schedule new execution after delay\n    // Only executes if no new calls come in during delay period\n    timeoutId = setTimeout(() => {\n      fn(...args);\n      timeoutId = null; // Clear reference for memory efficiency\n    }, delay);\n  };\n}\n\n/**\n * Throttle function to ensure a function is called at most once per time period.\n *\n * Why throttle:\n * - Limits execution frequency for continuous events (scroll, mousemove)\n * - Guarantees function fires at regular intervals during activity\n * - Better than debounce for real-time feedback (e.g., scroll position)\n * - Prevents performance degradation from high-frequency events\n *\n * Use throttle when: You want periodic updates during continuous action\n * Use debounce when: You only care about the final state after action stops\n *\n * @param fn - Function to throttle\n * @param limit - Minimum time in milliseconds between calls (typical: 100-250ms)\n * @returns Throttled function\n *\n * @example\n * ```ts\n * // Scroll position tracking: update every 100ms while scrolling\n * const throttledScroll = throttle(() => {\n *   const position = window.scrollY;\n *   updateScrollIndicator(position);\n * }, 100);\n * window.addEventListener('scroll', throttledScroll);\n * // Result: Updates 10x per second during scroll, not 100x\n *\n * // Mouse move tracking for drag operations\n * const throttledMouseMove = throttle((e: MouseEvent) => {\n *   updateDragPosition(e.clientX, e.clientY);\n * }, 16); // ~60fps\n * element.addEventListener('mousemove', throttledMouseMove);\n *\n * // API polling: check status every 5 seconds max\n * const throttledPoll = throttle(() => {\n *   checkStatus();\n * }, 5000);\n * ```\n */\nexport function throttle<T extends (...args: unknown[]) => unknown>(\n  fn: T,\n  limit: number,\n): (...args: Parameters<T>) => void {\n  // Flag to track if we're in throttle period\n  // When true, calls are ignored until period ends\n  let inThrottle = false;\n\n  return function throttled(...args: Parameters<T>) {\n    // Only execute if not currently in throttle period\n    if (!inThrottle) {\n      fn(...args); // Execute immediately on first call\n      inThrottle = true; // Enter throttle period\n\n      // Exit throttle period after limit milliseconds\n      // This ensures minimum time between executions\n      setTimeout(() => {\n        inThrottle = false;\n      }, limit);\n    }\n    // If inThrottle is true, this call is silently ignored\n    // This is the key difference from debounce\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,SAAgB,SACd,IACA,OACkC;CAGlC,IAAI,YAAkD;AAEtD,QAAO,SAAS,UAAU,GAAG,MAAqB;AAGhD,MAAI,cAAc,KAChB,cAAa,UAAU;AAKzB,cAAY,iBAAiB;AAC3B,MAAG,GAAG,KAAK;AACX,eAAY;KACX,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0Cb,SAAgB,SACd,IACA,OACkC;CAGlC,IAAI,aAAa;AAEjB,QAAO,SAAS,UAAU,GAAG,MAAqB;AAEhD,MAAI,CAAC,YAAY;AACf,MAAG,GAAG,KAAK;AACX,gBAAa;AAIb,oBAAiB;AACf,iBAAa;MACZ,MAAM"}

package/index.d.mts

@@ -0,0 +1,4 @@
+import { cn } from "./cn.mjs";
+import { formatRelativeDate } from "./date.mjs";
+import { debounce, throttle } from "./debounce.mjs";
+export { cn, debounce, formatRelativeDate, throttle };

package/index.mjs

@@ -0,0 +1,5 @@
+import { cn } from "./cn.mjs";
+import { formatRelativeDate } from "./date.mjs";
+import { debounce, throttle } from "./debounce.mjs";
+
+export { cn, debounce, formatRelativeDate, throttle };

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@od-oneapp/utils",
+  "version": "2026.2.2001-canary.1",
+  "description": "Shared utility functions",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "types": "./index.d.mts"
+    }
+  },
+  "peerDependenciesMeta": {},
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OneDigital-Product/monorepo.git",
+    "directory": "platform/packages/utils"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  }
+}