@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/utils/errors.md

@@ -1,451 +0,0 @@
-# Error Handling Patterns
-
-Patterns for handling errors gracefully.
-
-## Custom Error Classes
-
-```typescript
-// lib/errors.ts
-export class AppError extends Error {
-  constructor(
-    message: string,
-    public code: string,
-    public statusCode: number = 500,
-    public details?: Record<string, any>
-  ) {
-    super(message)
-    this.name = 'AppError'
-    Error.captureStackTrace(this, this.constructor)
-  }
-
-  toJSON() {
-    return {
-      error: {
-        code: this.code,
-        message: this.message,
-        details: this.details
-      }
-    }
-  }
-}
-
-export class ValidationError extends AppError {
-  constructor(message: string, details?: Record<string, string[]>) {
-    super(message, 'VALIDATION_ERROR', 400, details)
-    this.name = 'ValidationError'
-  }
-}
-
-export class NotFoundError extends AppError {
-  constructor(resource: string, id?: string) {
-    super(
-      id ? `${resource} with ID ${id} not found` : `${resource} not found`,
-      'NOT_FOUND',
-      404
-    )
-    this.name = 'NotFoundError'
-  }
-}
-
-export class UnauthorizedError extends AppError {
-  constructor(message = 'Unauthorized') {
-    super(message, 'UNAUTHORIZED', 401)
-    this.name = 'UnauthorizedError'
-  }
-}
-
-export class ForbiddenError extends AppError {
-  constructor(message = 'Forbidden') {
-    super(message, 'FORBIDDEN', 403)
-    this.name = 'ForbiddenError'
-  }
-}
-
-export class ConflictError extends AppError {
-  constructor(message: string) {
-    super(message, 'CONFLICT', 409)
-    this.name = 'ConflictError'
-  }
-}
-
-export class RateLimitError extends AppError {
-  constructor(retryAfter?: number) {
-    super('Too many requests', 'RATE_LIMIT_EXCEEDED', 429, { retryAfter })
-    this.name = 'RateLimitError'
-  }
-}
-```
-
-## API Error Handler
-
-```typescript
-// lib/api/error-handler.ts
-import { NextResponse } from 'next/server'
-import { AppError } from '@/lib/errors'
-import { ZodError } from 'zod'
-import { Prisma } from '@prisma/client'
-
-export function handleApiError(error: unknown): NextResponse {
-  console.error('API Error:', error)
-
-  // Custom app errors
-  if (error instanceof AppError) {
-    return NextResponse.json(error.toJSON(), { status: error.statusCode })
-  }
-
-  // Zod validation errors
-  if (error instanceof ZodError) {
-    return NextResponse.json(
-      {
-        error: {
-          code: 'VALIDATION_ERROR',
-          message: 'Validation failed',
-          details: error.flatten().fieldErrors
-        }
-      },
-      { status: 400 }
-    )
-  }
-
-  // Prisma errors
-  if (error instanceof Prisma.PrismaClientKnownRequestError) {
-    switch (error.code) {
-      case 'P2002':
-        return NextResponse.json(
-          {
-            error: {
-              code: 'CONFLICT',
-              message: 'A record with this value already exists',
-              details: { field: error.meta?.target }
-            }
-          },
-          { status: 409 }
-        )
-      case 'P2025':
-        return NextResponse.json(
-          {
-            error: {
-              code: 'NOT_FOUND',
-              message: 'Record not found'
-            }
-          },
-          { status: 404 }
-        )
-      default:
-        return NextResponse.json(
-          {
-            error: {
-              code: 'DATABASE_ERROR',
-              message: 'Database operation failed'
-            }
-          },
-          { status: 500 }
-        )
-    }
-  }
-
-  // Unknown errors
-  return NextResponse.json(
-    {
-      error: {
-        code: 'INTERNAL_ERROR',
-        message:
-          process.env.NODE_ENV === 'development'
-            ? (error as Error).message
-            : 'An unexpected error occurred'
-      }
-    },
-    { status: 500 }
-  )
-}
-
-// Wrapper for API routes
-type Handler = (...args: any[]) => Promise<NextResponse>
-
-export function withErrorHandler(handler: Handler): Handler {
-  return async (...args) => {
-    try {
-      return await handler(...args)
-    } catch (error) {
-      return handleApiError(error)
-    }
-  }
-}
-```
-
-## React Error Boundary
-
-```tsx
-// components/ErrorBoundary.tsx
-'use client'
-
-import { Component, ReactNode } from 'react'
-
-interface Props {
-  children: ReactNode
-  fallback?: ReactNode
-  onError?: (error: Error, errorInfo: React.ErrorInfo) => void
-}
-
-interface State {
-  hasError: boolean
-  error?: Error
-}
-
-export class ErrorBoundary extends Component<Props, State> {
-  constructor(props: Props) {
-    super(props)
-    this.state = { hasError: false }
-  }
-
-  static getDerivedStateFromError(error: Error): State {
-    return { hasError: true, error }
-  }
-
-  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
-    console.error('Error boundary caught:', error, errorInfo)
-    this.props.onError?.(error, errorInfo)
-  }
-
-  render() {
-    if (this.state.hasError) {
-      if (this.props.fallback) {
-        return this.props.fallback
-      }
-
-      return (
-        <div className="flex min-h-[200px] flex-col items-center justify-center rounded-lg border border-red-200 bg-red-50 p-6">
-          <h2 className="mb-2 text-lg font-semibold text-red-800">
-            Something went wrong
-          </h2>
-          <p className="mb-4 text-sm text-red-600">
-            {this.state.error?.message ?? 'An unexpected error occurred'}
-          </p>
-          <button
-            onClick={() => this.setState({ hasError: false, error: undefined })}
-            className="rounded bg-red-600 px-4 py-2 text-sm text-white hover:bg-red-700"
-          >
-            Try again
-          </button>
-        </div>
-      )
-    }
-
-    return this.props.children
-  }
-}
-```
-
-## Next.js Error Page
-
-```tsx
-// app/error.tsx
-'use client'
-
-import { useEffect } from 'react'
-
-export default function Error({
-  error,
-  reset
-}: {
-  error: Error & { digest?: string }
-  reset: () => void
-}) {
-  useEffect(() => {
-    // Log to error reporting service
-    console.error('Page error:', error)
-  }, [error])
-
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center">
-      <div className="text-center">
-        <h1 className="mb-4 text-4xl font-bold">Something went wrong</h1>
-        <p className="mb-6 text-gray-600">
-          We apologize for the inconvenience. Please try again.
-        </p>
-        <button
-          onClick={reset}
-          className="rounded bg-blue-600 px-6 py-2 text-white hover:bg-blue-700"
-        >
-          Try again
-        </button>
-      </div>
-    </div>
-  )
-}
-
-// app/not-found.tsx
-import Link from 'next/link'
-
-export default function NotFound() {
-  return (
-    <div className="flex min-h-screen flex-col items-center justify-center">
-      <div className="text-center">
-        <h1 className="mb-2 text-6xl font-bold text-gray-900">404</h1>
-        <h2 className="mb-4 text-2xl font-semibold text-gray-700">
-          Page not found
-        </h2>
-        <p className="mb-6 text-gray-600">
-          The page you're looking for doesn't exist.
-        </p>
-        <Link
-          href="/"
-          className="rounded bg-blue-600 px-6 py-2 text-white hover:bg-blue-700"
-        >
-          Go home
-        </Link>
-      </div>
-    </div>
-  )
-}
-```
-
-## Async Error Handling Hook
-
-```typescript
-// hooks/useAsyncError.ts
-'use client'
-
-import { useState, useCallback } from 'react'
-
-interface UseAsyncErrorReturn<T> {
-  execute: (...args: any[]) => Promise<T | undefined>
-  data: T | undefined
-  error: Error | null
-  isLoading: boolean
-  reset: () => void
-}
-
-export function useAsyncError<T>(
-  asyncFn: (...args: any[]) => Promise<T>
-): UseAsyncErrorReturn<T> {
-  const [data, setData] = useState<T>()
-  const [error, setError] = useState<Error | null>(null)
-  const [isLoading, setIsLoading] = useState(false)
-
-  const execute = useCallback(
-    async (...args: any[]) => {
-      setIsLoading(true)
-      setError(null)
-
-      try {
-        const result = await asyncFn(...args)
-        setData(result)
-        return result
-      } catch (err) {
-        const error = err instanceof Error ? err : new Error(String(err))
-        setError(error)
-        return undefined
-      } finally {
-        setIsLoading(false)
-      }
-    },
-    [asyncFn]
-  )
-
-  const reset = useCallback(() => {
-    setData(undefined)
-    setError(null)
-    setIsLoading(false)
-  }, [])
-
-  return { execute, data, error, isLoading, reset }
-}
-```
-
-## Result Type Pattern
-
-```typescript
-// lib/result.ts
-type Result<T, E = Error> =
-  | { success: true; data: T }
-  | { success: false; error: E }
-
-export function ok<T>(data: T): Result<T, never> {
-  return { success: true, data }
-}
-
-export function err<E>(error: E): Result<never, E> {
-  return { success: false, error }
-}
-
-// Usage
-async function createUser(data: UserInput): Promise<Result<User, AppError>> {
-  try {
-    const user = await prisma.user.create({ data })
-    return ok(user)
-  } catch (error) {
-    if (error instanceof Prisma.PrismaClientKnownRequestError) {
-      if (error.code === 'P2002') {
-        return err(new ConflictError('Email already exists'))
-      }
-    }
-    return err(new AppError('Failed to create user', 'CREATE_FAILED'))
-  }
-}
-
-// In handler
-const result = await createUser(data)
-
-if (!result.success) {
-  return NextResponse.json(result.error.toJSON(), {
-    status: result.error.statusCode
-  })
-}
-
-return NextResponse.json(result.data)
-```
-
-## Toast Error Display
-
-```tsx
-// hooks/useErrorToast.ts
-'use client'
-
-import { useCallback } from 'react'
-import { toast } from 'sonner'
-
-interface ApiError {
-  error: {
-    code: string
-    message: string
-    details?: Record<string, any>
-  }
-}
-
-export function useErrorToast() {
-  const showError = useCallback((error: unknown) => {
-    if (error instanceof Response) {
-      error.json().then((data: ApiError) => {
-        toast.error(data.error.message)
-      })
-      return
-    }
-
-    if (error instanceof Error) {
-      toast.error(error.message)
-      return
-    }
-
-    toast.error('An unexpected error occurred')
-  }, [])
-
-  return { showError }
-}
-
-// Usage
-const { showError } = useErrorToast()
-
-try {
-  await submitForm(data)
-} catch (error) {
-  showError(error)
-}
-```
-
-## When to Use
-
-- API error responses
-- Form validation
-- Async operations
-- Component error boundaries