cms-renderer 0.0.0 → 0.1.0

package/lib/data-utils.ts

@@ -1,572 +0,0 @@
-/**
- * Data Fetching Utilities
- *
- * Three implementations showing the progression from naive to production-ready:
- * - v1 (Naive): Direct await, crashes on any error
- * - v2 (Defensive): Try-catch with null fallback
- * - v3 (Robust): Result type, retry logic, timeout support
- *
- * The robust version (v3) is exported as the default `fetchPage`.
- */
-
-import { err, ok, type Result } from './result';
-import type { BlockData } from './types';
-
-// -----------------------------------------------------------------------------
-// Types
-// -----------------------------------------------------------------------------
-
-/**
- * Page structure returned by the tRPC API.
- */
-export interface Page {
-  slug: string;
-  title: string;
-  blocks: BlockData[];
-}
-
-/**
- * Error codes for data fetching failures.
- */
-export const FetchErrorCode = {
-  INVALID_SLUG: 'INVALID_SLUG',
-  NOT_FOUND: 'NOT_FOUND',
-  NETWORK_ERROR: 'NETWORK_ERROR',
-  TIMEOUT: 'TIMEOUT',
-  PARSE_ERROR: 'PARSE_ERROR',
-  SERVER_ERROR: 'SERVER_ERROR',
-  RETRY_EXHAUSTED: 'RETRY_EXHAUSTED',
-} as const;
-
-export type FetchErrorCode = (typeof FetchErrorCode)[keyof typeof FetchErrorCode];
-
-/**
- * Structured error for data fetching failures.
- */
-export interface FetchError {
-  code: FetchErrorCode;
-  message: string;
-  cause?: Error;
-  retryCount?: number;
-}
-
-/**
- * Options for robust data fetching.
- */
-export interface FetchOptions {
-  /**
-   * Timeout in milliseconds.
-   * @default 10000 (10 seconds)
-   */
-  timeout?: number;
-
-  /**
-   * Number of retry attempts for transient failures.
-   * @default 3
-   */
-  retries?: number;
-
-  /**
-   * Base delay between retries in milliseconds.
-   * Uses exponential backoff: delay * 2^attempt
-   * @default 1000 (1 second)
-   */
-  retryDelay?: number;
-
-  /**
-   * AbortSignal for cancellation support.
-   */
-  signal?: AbortSignal;
-}
-
-// -----------------------------------------------------------------------------
-// Constants
-// -----------------------------------------------------------------------------
-
-const DEFAULT_TIMEOUT = 10_000; // 10 seconds
-const DEFAULT_RETRIES = 3;
-const DEFAULT_RETRY_DELAY = 1_000; // 1 second
-
-/**
- * HTTP status codes that indicate transient failures (should retry).
- */
-const TRANSIENT_STATUS_CODES = [408, 429, 500, 502, 503, 504] as const;
-
-// -----------------------------------------------------------------------------
-// Mock Data Store (for demonstration)
-// -----------------------------------------------------------------------------
-
-/**
- * Simulated data store.
- * In production, this would be replaced with actual tRPC/API calls.
- */
-const mockPages: Record<string, Page> = {
-  demo: {
-    slug: 'demo',
-    title: 'Demo Page',
-    blocks: [
-      {
-        id: 'mock-header-1',
-        type: 'header',
-        content: {
-          headline: 'Welcome',
-          alignment: 'center',
-        },
-      },
-      {
-        id: 'mock-article-1',
-        type: 'article',
-        content: {
-          headline: 'Getting Started',
-          body: '## Introduction\n\nThis is a demo article.',
-        },
-      },
-    ],
-  },
-  about: {
-    slug: 'about',
-    title: 'About Us',
-    blocks: [
-      {
-        id: 'mock-header-2',
-        type: 'header',
-        content: {
-          headline: 'About Our Company',
-          alignment: 'left',
-        },
-      },
-    ],
-  },
-};
-
-// -----------------------------------------------------------------------------
-// Helper Functions
-// -----------------------------------------------------------------------------
-
-/**
- * Creates a FetchError with the given code and message.
- */
-function createFetchError(
-  code: FetchErrorCode,
-  message: string,
-  options: { cause?: Error; retryCount?: number } = {}
-): FetchError {
-  return { code, message, ...options };
-}
-
-/**
- * Delays execution for the specified duration.
- */
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Calculates exponential backoff delay.
- */
-function exponentialBackoff(baseDelay: number, attempt: number): number {
-  // Add jitter to prevent thundering herd
-  const jitter = Math.random() * 100;
-  return baseDelay * 2 ** attempt + jitter;
-}
-
-/**
- * Checks if an error represents a transient failure that should be retried.
- */
-function isTransientError(error: unknown): boolean {
-  if (error instanceof Error) {
-    // Network errors
-    if (error.name === 'TypeError' && error.message.includes('fetch')) {
-      return true;
-    }
-    // Check for HTTP status codes in error message
-    for (const code of TRANSIENT_STATUS_CODES) {
-      if (error.message.includes(String(code))) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-/**
- * Simulates a network request with configurable behavior.
- * In production, this would be an actual fetch/tRPC call.
- */
-async function simulateFetch(slug: string, signal?: AbortSignal): Promise<Page> {
-  // Simulate network latency
-  await delay(50 + Math.random() * 100);
-
-  // Check for cancellation
-  if (signal?.aborted) {
-    throw new Error('Request aborted');
-  }
-
-  const page = mockPages[slug];
-  if (!page) {
-    const error = new Error(`Page not found: ${slug}`);
-    error.name = 'NotFoundError';
-    throw error;
-  }
-
-  return page;
-}
-
-// -----------------------------------------------------------------------------
-// V1: Naive Implementation
-// -----------------------------------------------------------------------------
-
-/**
- * Naive data fetcher - crashes on any error.
- *
- * DO NOT USE IN PRODUCTION. This is for demonstration only.
- *
- * Problems:
- * - No input validation
- * - No error handling
- * - Will crash the entire app on network failure
- * - No timeout protection
- * - No retry logic for transient failures
- *
- * @example
- * ```ts
- * // This throws if slug is invalid or network fails
- * const page = await fetchPageV1('demo');
- * ```
- */
-export async function fetchPageV1(slug: string): Promise<Page> {
-  // Direct await - any error crashes the caller
-  return simulateFetch(slug);
-}
-
-// -----------------------------------------------------------------------------
-// V2: Defensive Implementation
-// -----------------------------------------------------------------------------
-
-/**
- * Defensive data fetcher - catches errors but loses context.
- *
- * Better than v1 but still problematic:
- * - Returns null on any error (loses error details)
- * - Caller can't distinguish between 404 and network failure
- * - No retry logic for transient failures
- * - No timeout protection
- *
- * @example
- * ```ts
- * const page = await fetchPageV2(slug);
- * if (!page) {
- *   // What went wrong? 404? Network? Timeout? We don't know.
- *   return <NotFound />;
- * }
- * ```
- */
-export async function fetchPageV2(slug: string): Promise<Page | null> {
-  try {
-    // Basic validation
-    if (!slug || typeof slug !== 'string') {
-      return null;
-    }
-
-    return await simulateFetch(slug);
-  } catch {
-    // All errors become null - we lose valuable context
-    return null;
-  }
-}
-
-// -----------------------------------------------------------------------------
-// V3: Robust Implementation
-// -----------------------------------------------------------------------------
-
-/**
- * Robust data fetcher - production-ready with full error context.
- *
- * Features:
- * - Input validation with specific error codes
- * - Result type for explicit error handling
- * - Automatic retry with exponential backoff
- * - Timeout support via AbortController
- * - Distinguishes between error types (404 vs network vs timeout)
- * - Preserves error context for debugging
- *
- * @param slug - Page slug to fetch
- * @param options - Fetch options (timeout, retries, etc.)
- * @returns Result containing the page data or a structured error
- *
- * @example
- * ```ts
- * const result = await fetchPageV3('demo', {
- *   timeout: 5000,
- *   retries: 3,
- * });
- *
- * if (!result.ok) {
- *   switch (result.error.code) {
- *     case 'NOT_FOUND':
- *       return <NotFoundPage slug={slug} />;
- *     case 'TIMEOUT':
- *       return <TimeoutError onRetry={handleRetry} />;
- *     case 'NETWORK_ERROR':
- *       return <NetworkError message={result.error.message} />;
- *     case 'RETRY_EXHAUSTED':
- *       return <RetryExhausted attempts={result.error.retryCount} />;
- *     default:
- *       return <GenericError />;
- *   }
- * }
- *
- * return <PageRenderer page={result.value} />;
- * ```
- */
-export async function fetchPageV3(
-  slug: string,
-  options: FetchOptions = {}
-): Promise<Result<Page, FetchError>> {
-  const {
-    timeout = DEFAULT_TIMEOUT,
-    retries = DEFAULT_RETRIES,
-    retryDelay = DEFAULT_RETRY_DELAY,
-    signal: externalSignal,
-  } = options;
-
-  // 1. Validate input
-  if (slug === null || slug === undefined) {
-    return err(
-      createFetchError(
-        FetchErrorCode.INVALID_SLUG,
-        `Slug must be a string, received ${slug === null ? 'null' : 'undefined'}`
-      )
-    );
-  }
-
-  if (typeof slug !== 'string') {
-    return err(
-      createFetchError(
-        FetchErrorCode.INVALID_SLUG,
-        `Slug must be a string, received ${typeof slug}`
-      )
-    );
-  }
-
-  const trimmedSlug = slug.trim();
-  if (trimmedSlug.length === 0) {
-    return err(createFetchError(FetchErrorCode.INVALID_SLUG, 'Slug cannot be empty'));
-  }
-
-  // 2. Create abort controller for timeout
-  const controller = new AbortController();
-  const { signal } = controller;
-
-  // Link external signal if provided
-  if (externalSignal) {
-    externalSignal.addEventListener('abort', () => controller.abort());
-  }
-
-  // 3. Set up timeout
-  const timeoutId = setTimeout(() => controller.abort(), timeout);
-
-  // 4. Attempt fetch with retry logic
-  let lastError: Error | undefined;
-  let attempt = 0;
-
-  try {
-    while (attempt <= retries) {
-      try {
-        const page = await simulateFetch(trimmedSlug, signal);
-        clearTimeout(timeoutId);
-        return ok(page);
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-
-        // Check for abort/timeout
-        if (signal.aborted) {
-          clearTimeout(timeoutId);
-          return err(
-            createFetchError(FetchErrorCode.TIMEOUT, `Request timed out after ${timeout}ms`, {
-              cause: lastError,
-            })
-          );
-        }
-
-        // Check for 404 (not retryable)
-        if (lastError.name === 'NotFoundError') {
-          clearTimeout(timeoutId);
-          return err(
-            createFetchError(FetchErrorCode.NOT_FOUND, `Page "${trimmedSlug}" not found`, {
-              cause: lastError,
-            })
-          );
-        }
-
-        // Check if we should retry
-        if (attempt < retries && isTransientError(lastError)) {
-          attempt++;
-          const backoff = exponentialBackoff(retryDelay, attempt);
-          if (process.env.NODE_ENV === 'development') {
-            console.warn(
-              `[fetchPageV3] Retry ${attempt}/${retries} for "${trimmedSlug}" after ${Math.round(backoff)}ms`
-            );
-          }
-          await delay(backoff);
-          continue;
-        }
-
-        // No more retries or non-transient error
-        break;
-      }
-    }
-
-    // 5. All retries exhausted
-    clearTimeout(timeoutId);
-
-    if (attempt >= retries) {
-      return err(
-        createFetchError(FetchErrorCode.RETRY_EXHAUSTED, `Failed after ${retries} retry attempts`, {
-          cause: lastError,
-          retryCount: attempt,
-        })
-      );
-    }
-
-    // Non-retryable error
-    return err(
-      createFetchError(
-        FetchErrorCode.NETWORK_ERROR,
-        lastError?.message ?? 'Unknown network error',
-        { cause: lastError }
-      )
-    );
-  } catch (error) {
-    clearTimeout(timeoutId);
-    const cause = error instanceof Error ? error : new Error(String(error));
-    return err(
-      createFetchError(FetchErrorCode.SERVER_ERROR, `Unexpected error: ${cause.message}`, { cause })
-    );
-  }
-}
-
-// -----------------------------------------------------------------------------
-// Default Export
-// -----------------------------------------------------------------------------
-
-/**
- * Production-ready page fetcher.
- *
- * This is an alias for `fetchPageV3` - the robust implementation
- * with validation, retry logic, and Result-based error handling.
- *
- * @example
- * ```ts
- * import { fetchPage } from '@/lib/data-utils';
- *
- * const result = await fetchPage('demo');
- * if (!result.ok) {
- *   // Handle error with full context
- *   console.error(`[${result.error.code}] ${result.error.message}`);
- *   return null;
- * }
- * return result.value;
- * ```
- */
-export const fetchPage = fetchPageV3;
-
-// -----------------------------------------------------------------------------
-// Utility Functions
-// -----------------------------------------------------------------------------
-
-/**
- * Validates a page slug format.
- *
- * @param slug - Slug to validate
- * @returns true if slug is valid format
- */
-export function isValidSlug(slug: string): boolean {
-  // Slugs should be lowercase, alphanumeric with hyphens
-  return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug);
-}
-
-/**
- * Normalizes a slug (lowercase, trim, replace spaces with hyphens).
- *
- * @param input - Raw input to normalize
- * @returns Normalized slug
- */
-export function normalizeSlug(input: string): string {
-  return input
-    .toLowerCase()
-    .trim()
-    .replace(/\s+/g, '-')
-    .replace(/[^a-z0-9-]/g, '')
-    .replace(/-+/g, '-')
-    .replace(/^-|-$/g, '');
-}
-
-/**
- * Prefetches multiple pages in parallel with Result types.
- *
- * @param slugs - Array of page slugs to fetch
- * @param options - Fetch options applied to all requests
- * @returns Array of Results for each page
- *
- * @example
- * ```ts
- * const results = await prefetchPages(['home', 'about', 'blog']);
- * const errors = results.filter(r => !r.ok);
- * if (errors.length > 0) {
- *   console.warn(`${errors.length} pages failed to load`);
- * }
- * ```
- */
-export async function prefetchPages(
-  slugs: string[],
-  options?: FetchOptions
-): Promise<Result<Page, FetchError>[]> {
-  return Promise.all(slugs.map((slug) => fetchPageV3(slug, options)));
-}
-
-/**
- * Fetches a page with stale-while-revalidate semantics.
- * Returns cached data immediately if available, then updates in background.
- *
- * @param slug - Page slug to fetch
- * @param cache - Cache storage (e.g., Map, localStorage wrapper)
- * @param options - Fetch options
- * @returns Cached data or fresh fetch result
- */
-export async function fetchPageWithSWR(
-  slug: string,
-  cache: Map<string, { data: Page; timestamp: number }>,
-  options: FetchOptions & { maxAge?: number } = {}
-): Promise<Result<Page, FetchError>> {
-  const { maxAge = 60_000 } = options; // 1 minute default
-
-  const cached = cache.get(slug);
-  const now = Date.now();
-
-  // Return fresh cache immediately
-  if (cached && now - cached.timestamp < maxAge) {
-    return ok(cached.data);
-  }
-
-  // Fetch fresh data
-  const result = await fetchPageV3(slug, options);
-
-  // Update cache on success
-  if (result.ok) {
-    cache.set(slug, { data: result.value, timestamp: now });
-  }
-
-  // If fetch failed but we have stale cache, return it with warning
-  if (!result.ok && cached) {
-    if (process.env.NODE_ENV === 'development') {
-      console.warn(
-        `[fetchPageWithSWR] Returning stale cache for "${slug}" after fetch failure:`,
-        result.error.message
-      );
-    }
-    return ok(cached.data);
-  }
-
-  return result;
-}