1# Client Utilities
2 
3Pure functions for formatting, validation, transformation, and parsing.
4 
5## Quick Reference
6 
7| Category     | Examples                                      |
8| ------------ | --------------------------------------------- |
9| Formatters   | `formatCurrency`, `formatDate`, `formatBytes` |
10| Validators   | `isValidEmail`, `isValidUrl`, `isValidPhone`  |
11| Transformers | `slugify`, `truncate`, `capitalize`           |
12| Parsers      | `parseQuery`, `parseJSON`, `parseDate`        |
13 
14## Rules
15 
16**Pure functions:**
17 
18- Same input → same output
19- No side effects
20- No external state mutation
21- No API calls, no refs, no reactive
22 
23**When NOT to use utils:**
24 
25- Stateful logic → use composables
26- Vue-specific → use composables
27- Component logic → keep in component
28- API calls → use queries
29 
30## Structure
31 
32```ts
33// utils/formatters.ts
34export function formatCurrency(amount: number, currency = 'USD'): string {
35  return new Intl.NumberFormat('en-US', {
36    style: 'currency',
37    currency,
38  }).format(amount)
39}
40 
41export function formatRelativeTime(date: Date): string {
42  const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
43  const diff = date.getTime() - Date.now()
44  const days = Math.floor(diff / (1000 * 60 * 60 * 24))
45  return rtf.format(days, 'day')
46}
47```
48 
49**Naming:** Descriptive verbs (`formatCurrency`, `validateEmail`, `parseQuery`)
50**Organization:** Group by category (`formatters.ts`, `validators.ts`)
51**Exports:** Named exports only
52 
53## Examples by Category
54 
55**Formatters:**
56 
57```ts
58// utils/formatters.ts
59export function formatBytes(bytes: number): string { ... }
60export function formatPhone(phone: string): string { ... }
61```
62 
63**Validators:**
64 
65```ts
66// utils/validators.ts
67export function isValidEmail(email: string): boolean {
68  return /^[^\s@]+@[^\s@][^\s.@]*\.[^\s@]+$/.test(email)
69}
70 
71export function isValidUrl(url: string): boolean {
72  try { new URL(url); return true }
73  catch { return false }
74}
75```
76 
77**Transformers:**
78 
79```ts
80// utils/transformers.ts
81export function slugify(text: string): string {
82  return text.toLowerCase()
83    .replace(/[^\w\s-]/g, '')
84    .replace(/\s+/g, '-')
85}
86 
87export function truncate(text: string, length: number): string {
88  return text.length > length ? `${text.slice(0, length)}...` : text
89}
90```
91 
92**Parsers:**
93 
94```ts
95// utils/parsers.ts
96export function parseQuery(search: string): Record<string, string> {
97  return Object.fromEntries(new URLSearchParams(search))
98}
99 
100export function parseJSON<T>(json: string, fallback: T): T {
101  try { return JSON.parse(json) }
102  catch { return fallback }
103}
104```
105 
106## Common Mistakes
107 
108**Side effects (not pure):**
109 
110```ts
111// ❌ Wrong - mutates external state
112let count = 0
113export function increment() {
114  count++
115  return count
116}
117 
118// ✅ Correct - pure
119export function add(a: number, b: number): number {
120  return a + b
121}
122```
123 
124**Using utils for stateful logic:**
125 
126```ts
127// ❌ Wrong - should be composable
128export function useCounter() { ... }
129 
130// ✅ Correct - pure transformation
131export function formatCount(count: number): string { ... }
132```
133 
134## Organization
135 
136**Flat for small projects:**
137 
138```
139utils/
140├── formatters.ts
141├── validators.ts
142└── transformers.ts
143```
144 
145**Nested for large projects:**
146 
147```
148utils/
149├── formatters/
150│   ├── date.ts
151│   ├── currency.ts
152│   └── index.ts
153└── validators/
154    ├── email.ts
155    └── index.ts
156```
157