Skip to content
Shell
9.0 KB
Raw Blame

COMPONENTS.md

Code Patterns That Work

Patterns extracted from real projects. Copy, adapt, ship.


React Patterns

Async State Hook

Handle loading/error/data states cleanly.

type AsyncState<T> = 
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };

function useAsync<T>(asyncFn: () => Promise<T>, deps: any[] = []) {
  const [state, setState] = useState<AsyncState<T>>({ status: 'idle' });

  useEffect(() => {
    setState({ status: 'loading' });
    asyncFn()
      .then(data => setState({ status: 'success', data }))
      .catch(error => setState({ status: 'error', error }));
  }, deps);

  return state;
}

// Usage
const state = useAsync(() => fetchProjects(), []);
if (state.status === 'loading') return <Spinner />;
if (state.status === 'error') return <Error error={state.error} />;
if (state.status === 'success') return <List data={state.data} />;

Debounced Input

Prevent excessive API calls on user input.

function useDebouncedValue<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);

  return debouncedValue;
}

// Usage
function Search() {
  const [query, setQuery] = useState('');
  const debouncedQuery = useDebouncedValue(query, 300);

  useEffect(() => {
    if (debouncedQuery) {
      searchAPI(debouncedQuery);
    }
  }, [debouncedQuery]);

  return <input value={query} onChange={e => setQuery(e.target.value)} />;
}

Optimistic Updates

Update UI immediately, reconcile with server.

function useOptimisticUpdate<T>(
  initialData: T,
  updateFn: (data: T) => Promise<T>
) {
  const [data, setData] = useState(initialData);
  const [pending, setPending] = useState(false);

  const update = async (optimisticData: T) => {
    const previousData = data;
    setData(optimisticData); // Optimistic
    setPending(true);

    try {
      const serverData = await updateFn(optimisticData);
      setData(serverData); // Reconcile
    } catch (error) {
      setData(previousData); // Rollback
      throw error;
    } finally {
      setPending(false);
    }
  };

  return { data, update, pending };
}

Local Storage Sync

Persist state to localStorage with SSR safety.

function useLocalStorage<T>(key: string, initialValue: T) {
  const [storedValue, setStoredValue] = useState<T>(() => {
    if (typeof window === 'undefined') return initialValue;
    try {
      const item = window.localStorage.getItem(key);
      return item ? JSON.parse(item) : initialValue;
    } catch {
      return initialValue;
    }
  });

  const setValue = (value: T | ((val: T) => T)) => {
    const valueToStore = value instanceof Function ? value(storedValue) : value;
    setStoredValue(valueToStore);
    if (typeof window !== 'undefined') {
      window.localStorage.setItem(key, JSON.stringify(valueToStore));
    }
  };

  return [storedValue, setValue] as const;
}

API Patterns

Fetch Wrapper with Error Handling

class APIError extends Error {
  constructor(
    message: string,
    public status: number,
    public data?: any
  ) {
    super(message);
    this.name = 'APIError';
  }
}

async function api<T>(
  endpoint: string,
  options: RequestInit = {}
): Promise<T> {
  const response = await fetch(`${BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  if (!response.ok) {
    const data = await response.json().catch(() => null);
    throw new APIError(
      data?.message || 'Request failed',
      response.status,
      data
    );
  }

  return response.json();
}

// Usage
const projects = await api<Project[]>('/projects');
const created = await api<Project>('/projects', {
  method: 'POST',
  body: JSON.stringify({ name: 'New Project' }),
});

Retry with Exponential Backoff

async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries?: number; baseDelay?: number } = {}
): Promise<T> {
  const { maxRetries = 3, baseDelay = 1000 } = options;
  let lastError: Error;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;
      if (attempt < maxRetries - 1) {
        const delay = baseDelay * Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }

  throw lastError!;
}

// Usage
const data = await withRetry(() => api('/flaky-endpoint'), {
  maxRetries: 3,
  baseDelay: 500,
});

Rate Limiter

function createRateLimiter(maxRequests: number, windowMs: number) {
  const requests: number[] = [];

  return async function limit<T>(fn: () => Promise<T>): Promise<T> {
    const now = Date.now();
    
    // Remove old requests outside window
    while (requests.length && requests[0] < now - windowMs) {
      requests.shift();
    }

    if (requests.length >= maxRequests) {
      const waitTime = requests[0] + windowMs - now;
      await new Promise(resolve => setTimeout(resolve, waitTime));
      return limit(fn);
    }

    requests.push(now);
    return fn();
  };
}

// Usage
const limiter = createRateLimiter(10, 1000); // 10 requests per second
const result = await limiter(() => api('/endpoint'));

Data Patterns

ID Generator

// Simple unique ID (good for client-side)
function createId(): string {
  return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
}

// Prefixed ID (good for type identification)
function createPrefixedId(prefix: string): string {
  return `${prefix}_${createId()}`;
}

// Usage
const projectId = createPrefixedId('proj'); // "proj_lx1234_abc1234"
const versionId = createPrefixedId('ver');  // "ver_lx1235_def5678"

Deep Clone / Merge

function deepClone<T>(obj: T): T {
  return JSON.parse(JSON.stringify(obj));
}

function deepMerge<T extends object>(target: T, source: Partial<T>): T {
  const result = { ...target };
  
  for (const key in source) {
    const sourceValue = source[key];
    const targetValue = result[key];
    
    if (
      sourceValue &&
      typeof sourceValue === 'object' &&
      !Array.isArray(sourceValue) &&
      targetValue &&
      typeof targetValue === 'object'
    ) {
      result[key] = deepMerge(targetValue, sourceValue as any);
    } else if (sourceValue !== undefined) {
      result[key] = sourceValue as any;
    }
  }
  
  return result;
}

Safe JSON Parse

function safeJsonParse<T>(
  json: string,
  fallback: T
): T {
  try {
    return JSON.parse(json) as T;
  } catch {
    return fallback;
  }
}

// With validation
function parseAndValidate<T>(
  json: string,
  validator: (data: unknown) => data is T,
  fallback: T
): T {
  try {
    const parsed = JSON.parse(json);
    return validator(parsed) ? parsed : fallback;
  } catch {
    return fallback;
  }
}

UI Patterns

Keyboard Shortcut Hook

function useKeyboardShortcut(
  key: string,
  callback: () => void,
  modifiers: { ctrl?: boolean; meta?: boolean; shift?: boolean } = {}
) {
  useEffect(() => {
    const handler = (event: KeyboardEvent) => {
      const { ctrl, meta, shift } = modifiers;
      
      if (
        event.key.toLowerCase() === key.toLowerCase() &&
        (!ctrl || event.ctrlKey) &&
        (!meta || event.metaKey) &&
        (!shift || event.shiftKey)
      ) {
        event.preventDefault();
        callback();
      }
    };

    window.addEventListener('keydown', handler);
    return () => window.removeEventListener('keydown', handler);
  }, [key, callback, modifiers]);
}

// Usage
useKeyboardShortcut('s', handleSave, { meta: true }); // Cmd+S
useKeyboardShortcut('k', openSearch, { meta: true }); // Cmd+K

Click Outside Hook

function useClickOutside(
  ref: RefObject<HTMLElement>,
  callback: () => void
) {
  useEffect(() => {
    const handler = (event: MouseEvent) => {
      if (ref.current && !ref.current.contains(event.target as Node)) {
        callback();
      }
    };

    document.addEventListener('mousedown', handler);
    return () => document.removeEventListener('mousedown', handler);
  }, [ref, callback]);
}

// Usage
function Dropdown() {
  const [open, setOpen] = useState(false);
  const ref = useRef<HTMLDivElement>(null);
  
  useClickOutside(ref, () => setOpen(false));
  
  return (
    <div ref={ref}>
      <button onClick={() => setOpen(!open)}>Toggle</button>
      {open && <div>Dropdown content</div>}
    </div>
  );
}

Adding New Patterns

When you extract a reusable pattern:

### [Pattern Name]

[Brief description of what it does]

\`\`\`typescript
// Code here
\`\`\`

// Usage example

**Good for**: [Use cases]
**Extracted from**: [Project]

Remember

Don't abstract too early. Extract patterns after you've used them 2-3 times.