React vs Angular vs Vue — Context Re-render Cascade

// io.thecodeforge — React Server Components: production checkout pattern
//
// Architecture: RSC fetches pricing server-side (zero client JS bundle cost)
//               Client Component handles quantity interaction (hydrates independently)
//
// Why this split matters:
//   - Pricing data lives on the server — no client-side fetch, no loading spinner,
//     no risk of stale price from a client-side cache
//   - Client Component only ships the interactivity code — quantity input and line total
//   - Suspense boundary per item means one slow product doesn't block the entire list

import { Suspense } from 'react';
import CheckoutItem from './CheckoutItem'; // 'use client' — lives in browser bundle
import CheckoutItemSkeleton from './CheckoutItemSkeleton';

// No 'use client' directive = this component runs ONLY on the server
// It is never included in the browser JavaScript bundle
async function CheckoutProductList({ cartItemIds }) {
  // cache: 'no-store' is not optional here. Without it, Next.js App Router caches
  // this fetch response and serves it to subsequent requests for the cache TTL.
  // Users see wrong prices. The bug is completely silent — no error, no warning.
  // This is the most common RSC bug in production checkout flows.
  const response = await fetch(
    `https://api.internal/products?ids=${cartItemIds.join(',')}`,
    {
      cache: 'no-store', // Force fresh pricing on every request
      headers: { 'x-internal-token': process.env.INTERNAL_API_TOKEN },
    }
  );

  if (!response.ok) {
    // Throwing here surfaces to the nearest error.tsx boundary
    // The error boundary shows a user-friendly fallback instead of a broken page
    throw new Error(
      `Product pricing API returned ${response.status} for cart items: ${cartItemIds.join(',')}`
    );
  }

  const products = await response.json();

  return (
    <ul className="checkout-product-list" aria-label="Cart items">
      {products.map((product) => (
        // Suspense per item: each CheckoutItem hydrates independently
        // One slow item does not block the rest of the list
        <Suspense key={product.id} fallback={<CheckoutItemSkeleton />}>
          <CheckoutItem product={product} />
        </Suspense>
      ))}
    </ul>
  );
}

export default CheckoutProductList;


// --- CheckoutItem.jsx (Client Component — ships to browser bundle) ---
// This file lives at io/thecodeforge/checkout/CheckoutItem.jsx

'use client'; // This boundary sends everything below to the browser bundle

import { useState } from 'react';

function CheckoutItem({ product }) {
  const [quantity, setQuantity] = useState(1);

  // Derived value — compute from existing state, never store computed values in state
  // Storing lineTotal in state creates a sync problem: quantity and lineTotal can diverge
  const lineTotal = (product.priceInCents * quantity) / 100;

  function handleQuantityChange(e) {
    const parsed = parseInt(e.target.value, 10);
    // Guard against NaN and negative values from direct input editing
    if (!isNaN(parsed) && parsed > 0) {
      setQuantity(parsed);
    }
  }

  return (
    <li className="checkout-item">
      <span className="checkout-item__name">{product.name}</span>
      <input
        type="number"
        min="1"
        max="99"
        value={quantity}
        onChange={handleQuantityChange}
        aria-label={`Quantity for ${product.name}`}
        className="checkout-item__qty"
      />
      {/* toFixed(2) prevents floating-point display artifacts like £12.999999 */}
      <span className="checkout-item__total" aria-live="polite">
        £{lineTotal.toFixed(2)}
      </span>
    </li>
  );
}

export default CheckoutItem;

/*
 * Execution model:
 *
 * Server (per request):
 *   1. CheckoutProductList runs — fetches fresh pricing from internal API
 *   2. Renders HTML with real prices embedded — no client-side fetch needed
 *   3. Each CheckoutItem receives product data as a prop from server
 *
 * Client (after hydration):
 *   4. CheckoutItem hydrates — useState(1) initialises quantity
 *   5. User changes quantity input → handleQuantityChange → setQuantity
 *   6. lineTotal recalculates as derived value → span updates
 *   7. No server round-trip needed for line total calculation
 *
 * If pricing API fails:
 *   - throw new Error() in CheckoutProductList surfaces to error.tsx boundary
 *   - Boundary renders user-friendly 'Unable to load cart' message
 *   - No broken UI, no silent wrong prices
 */

// io.thecodeforge — Angular 18 Signals-based payment processing service
//
// Design principles demonstrated:
//   1. Service handles all state and side effects — component stays thin
//   2. Signals replace BehaviorSubject for simple state — less RxJS overhead
//   3. Computed signals for derived state — recalculate only when dependencies change
//   4. Private writable signals, public readonly surfaces — enforces immutability at call sites
//   5. firstValueFrom converts Observable to Promise — cleaner in async/await flows
//   6. User-safe error messages — raw error internals never reach the template

import { Injectable, signal, computed } from '@angular/core';
import { HttpClient, HttpErrorResponse } from '@angular/common/http';
import { firstValueFrom } from 'rxjs';

export type PaymentStatus = 'idle' | 'processing' | 'succeeded' | 'failed';

export interface PaymentIntent {
  intentId: string;
  amountInCents: number;
  currency: string;
  createdAt: string;
}

@Injectable({
  // providedIn: 'root' = singleton across the entire application
  // One source of truth for payment state — no accidental dual instances
  providedIn: 'root',
})
export class PaymentProcessingService {

  // Private writable signals — only this service mutates state
  // Components receive readonly signals — they cannot accidentally corrupt state
  private readonly _status = signal<PaymentStatus>('idle');
  private readonly _errorMessage = signal<string | null>(null);
  private readonly _lastIntent = signal<PaymentIntent | null>(null);

  // Computed signals: derived state recalculates only when the specific
  // signal it reads from changes — not on every change detection cycle
  readonly isProcessing = computed(() => this._status() === 'processing');
  readonly hasError = computed(() => this._errorMessage() !== null);
  readonly canRetry = computed(
    () => this._status() === 'failed' || this._status() === 'idle'
  );

  // Public readonly signal surfaces — what components bind to in templates
  // Template: <button [disabled]="paymentService.isProcessing()">Place Order</button>
  readonly status = this._status.asReadonly();
  readonly errorMessage = this._errorMessage.asReadonly();
  readonly lastIntent = this._lastIntent.asReadonly();

  constructor(private readonly http: HttpClient) {}

  async initiatePayment(cartId: string, amountInCents: number): Promise<void> {
    // Guard: prevents double-submission from impatient button clicks
    // The signal check is synchronous — no race condition possible here
    if (this._status() === 'processing') {
      console.warn('[PaymentProcessingService] initiatePayment called while already processing — ignoring');
      return;
    }

    this._status.set('processing');
    this._errorMessage.set(null); // Clear previous error on fresh attempt

    try {
      // firstValueFrom: converts the HttpClient Observable to a Promise
      // Cleaner than .pipe(take(1)).subscribe() for single-value async flows
      // HttpClient cancels the underlying request when the subscription completes
      const intent = await firstValueFrom(
        this.http.post<PaymentIntent>('/api/forge/payments/initiate', {
          cartId,
          amountInCents,
          // Include a client-generated idempotency key to prevent double-charges
          // on network retry — backend deduplicates on this key
          idempotencyKey: `${cartId}-${Date.now()}`,
        })
      );

      this._lastIntent.set(intent);
      this._status.set('succeeded');

    } catch (error) {
      // Classify the error for appropriate user messaging
      // Never expose raw error details, stack traces, or internal API messages to the UI
      const userMessage = this.classifyError(error);
      this._errorMessage.set(userMessage);
      this._status.set('failed');

      // Re-throw so the calling component can forward to error tracking (Sentry, Datadog)
      // The component does not need to know the error message — just that it happened
      throw error;
    }
  }

  resetPaymentState(): void {
    this._status.set('idle');
    this._errorMessage.set(null);
    this._lastIntent.set(null);
  }

  private classifyError(error: unknown): string {
    if (error instanceof HttpErrorResponse) {
      if (error.status === 402) {
        return 'Your payment method was declined. Please check your card details or try a different card.';
      }
      if (error.status === 503) {
        return 'Our payment service is temporarily unavailable. Please try again in a moment.';
      }
      if (error.status === 0) {
        // Status 0 = network failure, CORS error, or request cancelled
        return 'Unable to reach the payment service. Please check your connection and try again.';
      }
    }
    return 'Payment could not be processed. Please try again or contact support if the issue persists.';
  }
}

/*
 * Consuming component template (simplified):
 *
 * <button
 *   (click)="processPayment()"
 *   [disabled]="paymentService.isProcessing()"
 *   [class.loading]="paymentService.isProcessing()">
 *   {{ paymentService.isProcessing() ? 'Processing...' : 'Place Order' }}
 * </button>
 *
 * <p class="error-message" *ngIf="paymentService.hasError()">
 *   {{ paymentService.errorMessage() }}
 * </p>
 *
 * Signal changes drive template updates automatically.
 * No manual ChangeDetectorRef.detectChanges() calls needed.
 * No async pipe needed for simple state signals.
 */

// io.thecodeforge — Vue 3 Composition API: production inventory polling composable
//
// Use case: real-time stock level display in a warehouse management dashboard.
// This composable encapsulates the entire polling lifecycle — the consuming
// component has zero timer management responsibility.
//
// Why a composable instead of inline component logic:
//   - Reusable across any component that needs stock level data for a SKU
//   - Testable in isolation — pass a mock fetch, verify state transitions
//   - Lifecycle cleanup is guaranteed — onUnmounted fires even if the component
//     is destroyed by navigation, error boundary, or conditional rendering

import { ref, computed, onMounted, onUnmounted } from 'vue';

// Composable convention: 'use' prefix, accepts configuration parameters,
// returns reactive state and exposed methods.
// No Rules of Hooks restrictions — this can be called conditionally if needed.
export function useInventoryPolling(skuId, pollingIntervalMs = 5000) {
  const stockLevel = ref(null);  // null = data not yet received
  const isLoading = ref(false);
  const fetchError = ref(null);
  const lastUpdatedAt = ref(null);
  let pollingTimer = null; // Module-scoped reference — not reactive, just a cleanup handle

  // Computed: derived state recalculates automatically when stockLevel changes
  // This does not re-run on every render — only when stockLevel.value changes
  const isLowStock = computed(() => {
    if (stockLevel.value === null) return false; // Guard during initial load
    return stockLevel.value < 10; // Business rule: below 10 units = low stock alert
  });

  const stockStatusLabel = computed(() => {
    if (stockLevel.value === null) return 'Loading...';
    if (stockLevel.value === 0) return 'Out of stock';
    if (isLowStock.value) return `Low stock — ${stockLevel.value} remaining`;
    return `${stockLevel.value} in stock`;
  });

  async function fetchCurrentStock() {
    // Prevent request stacking — if a fetch is in flight, skip the next poll tick
    // Without this guard, slow API responses cause concurrent requests to accumulate
    if (isLoading.value) return;

    isLoading.value = true;
    fetchError.value = null;

    try {
      const response = await fetch(`/api/forge/inventory/${skuId}/stock-level`, {
        headers: { 'Cache-Control': 'no-cache' }, // Prevent browser caching stale stock counts
      });

      if (!response.ok) {
        // Include HTTP status — 403 (auth expired) and 503 (backend down)
        // are different problems requiring different handling in the UI
        throw new Error(`Inventory API returned ${response.status} for SKU ${skuId}`);
      }

      const payload = await response.json();
      stockLevel.value = payload.unitsAvailable;
      lastUpdatedAt.value = new Date();
    } catch (error) {
      fetchError.value = error.message;
      // Do not re-throw — polling should survive transient network failures.
      // The next interval tick will retry automatically.
      // If you need to track consecutive failures, add a failureCount ref here.
    } finally {
      isLoading.value = false;
    }
  }

  onMounted(() => {
    // Immediate fetch on mount — do not make the user wait for the first interval
    fetchCurrentStock();
    // Start polling after the immediate fetch resolves (or fails)
    pollingTimer = setInterval(fetchCurrentStock, pollingIntervalMs);
  });

  // CRITICAL: onUnmounted cleanup prevents the most common Vue composable bug.
  // Vue does NOT warn you when a setInterval or WebSocket connection leaks
  // after component destruction. The interval keeps firing, makes network
  // requests to a component that no longer exists, and slowly degrades
  // browser performance over a session as leaked intervals accumulate.
  // React at least logs a warning about state updates on unmounted components.
  // Vue is silent. The leak is invisible until it becomes a performance complaint.
  onUnmounted(() => {
    if (pollingTimer !== null) {
      clearInterval(pollingTimer);
      pollingTimer = null; // Clear the reference — allows GC to collect
    }
  });

  return {
    stockLevel,        // Readonly in practice — external code should call refetch(), not mutate
    isLowStock,        // Computed — auto-updates when stockLevel changes
    stockStatusLabel,  // Computed — human-readable status string for display
    isLoading,         // Show skeleton or spinner while fetch is in flight
    fetchError,        // Display error state in the template
    lastUpdatedAt,     // Show 'Last updated 30s ago' in the UI if needed
    refetch: fetchCurrentStock, // Manual refresh for a 'Refresh' button
  };
}

// --- Usage in WarehouseDashboard.vue ---
//
// <script setup>
// import { useInventoryPolling } from '@/composables/useInventoryPolling';
//
// const props = defineProps({ skuId: String });
// const { stockLevel, isLowStock, stockStatusLabel, fetchError, refetch } =
//   useInventoryPolling(props.skuId, 3000); // Poll every 3 seconds for this dashboard
// </script>
//
// <template>
//   <div :class="{ 'alert-low-stock': isLowStock }">
//     <span v-if="fetchError" class="error">{{ fetchError }}</span>
//     <span v-else class="stock-status">{{ stockStatusLabel }}</span>
//     <button @click="refetch" class="refresh-btn">Refresh</button>
//   </div>
// </template>
//
// The :class binding updates automatically when isLowStock changes.
// No watcher, no computed property in the component — the composable handles it.

// io.thecodeforge — Framework Decision Matrix
//
// This is not executable application code.
// It is a decision model expressed in code format so the selection logic
// is auditable, version-controlled, and reproducible.
//
// Instructions:
//   1. Fill in PROJECT_CONSTRAINTS with your actual project parameters
//   2. Run with: node FrameworkDecisionMatrix.js
//   3. Copy the output into your Architecture Decision Record (ADR)
//   4. Document WHY each constraint has the value it does — the reasoning
//      matters more than the score

const PROJECT_CONSTRAINTS = {
  // How many frontend engineers at steady state (not at peak hiring)
  teamSize: 4,

  // When does the first working version need to reach users?
  // 'weeks': MVP in 4-8 weeks
  // 'months': standard product delivery, 2-4 months
  // 'quarters': enterprise timeline, 6+ months acceptable
  timeToFirstShip: 'weeks',

  // How long will this product need active maintenance and development?
  projectLifespan: '2+ years',

  // How strictly is TypeScript enforced in your org?
  // 'required': strict mode, no any, enforced in CI
  // 'preferred': encouraged but not gate-keeping PRs
  // 'optional': no TypeScript mandate
  tsEnforcement: 'preferred',

  // How important is hiring more frontend engineers in the next 6 months?
  // 'critical': you need to hire 3+ engineers soon
  // 'high': 1-2 hires likely
  // 'low': team is stable, no near-term hiring plan
  hiringPriority: 'high',

  // Are your users on mobile devices with limited data and slow connections?
  // true = bundle size directly affects user retention and conversion
  mobileFirstAudience: false,

  // Finance, healthcare, government — auditability of data flow is a compliance requirement
  regulatedIndustry: false,

  // Do you need server-side rendering for SEO or initial load performance?
  ssrRequired: true,
};

// Scoring model: 0 = poor fit for this constraint, 3 = ideal fit
// Adjust weights by multiplying scores for constraints you consider critical
function scoreFrameworks(constraints) {
  const scores = { react: 0, angular: 0, vue: 0 };

  // ── Team size ──────────────────────────────────────────────────────────────
  // Angular enforced structure scales to large teams.
  // Vue's reduced ceremony works best for small teams.
  // React spans the middle but needs architectural conventions to scale.
  if (constraints.teamSize >= 10) {
    scores.angular += 3; scores.react += 2; scores.vue += 1;
  } else if (constraints.teamSize >= 5) {
    scores.react += 3; scores.vue += 2; scores.angular += 1;
  } else {
    scores.vue += 3; scores.react += 2; scores.angular += 0;
  }

  // ── Time to first ship ─────────────────────────────────────────────────────
  // Angular's ceremony tax is highest in the first weeks.
  // Vue minimises decisions. React is fast with good conventions.
  if (constraints.timeToFirstShip === 'weeks') {
    scores.vue += 3; scores.react += 2; scores.angular += 0;
  } else if (constraints.timeToFirstShip === 'months') {
    scores.react += 3; scores.vue += 2; scores.angular += 2;
  } else { // 'quarters'
    scores.react += 2; scores.angular += 3; scores.vue += 2;
  }

  // ── TypeScript enforcement ─────────────────────────────────────────────────
  // Angular is TypeScript-first by design — it cannot be circumvented.
  // React with TSX is excellent. Vue 3 is good but has generic edge cases.
  if (constraints.tsEnforcement === 'required') {
    scores.angular += 3; scores.react += 2; scores.vue += 1;
  } else if (constraints.tsEnforcement === 'preferred') {
    scores.react += 3; scores.angular += 2; scores.vue += 2;
  } else { // 'optional'
    scores.vue += 3; scores.react += 2; scores.angular += 1;
  }

  // ── Hiring pipeline ────────────────────────────────────────────────────────
  // React ~46% of job postings. Angular ~28%. Vue ~14%.
  // A larger talent pool means faster hiring and lower compensation premiums.
  if (constraints.hiringPriority === 'critical') {
    scores.react += 3; scores.angular += 1; scores.vue += 0;
  } else if (constraints.hiringPriority === 'high') {
    scores.react += 3; scores.angular += 1; scores.vue += 1;
  } else { // 'low'
    scores.react += 2; scores.angular += 2; scores.vue += 2;
  }

  // ── Mobile-first audience and bundle size sensitivity ─────────────────────
  // Vue ~33KB | React ~45KB | Angular ~65KB (gzipped, minimal app)
  if (constraints.mobileFirstAudience) {
    scores.vue += 3; scores.react += 1; scores.angular += 0;
  } else {
    // Bundle size advantage is real but not decisive for non-mobile-first
    scores.vue += 1; scores.react += 1; scores.angular += 1;
  }

  // ── Regulated industry ─────────────────────────────────────────────────────
  // Angular's explicit DI, module boundaries, and audit trail aids compliance
  if (constraints.regulatedIndustry) {
    scores.angular += 3; scores.react += 1; scores.vue += 0;
  }

  // ── SSR requirements ───────────────────────────────────────────────────────
  // All three have mature SSR solutions in 2026.
  // Next.js RSC is the most mature. Nuxt 4 is production-ready.
  // Angular Universal + Analog is the least battle-tested at scale.
  if (constraints.ssrRequired) {
    scores.react += 3; scores.vue += 2; scores.angular += 1;
  }

  return scores;
}

const scores = scoreFrameworks(PROJECT_CONSTRAINTS);

const ranked = Object.entries(scores)
  .sort(([, a], [, b]) => b - a)
  .map(([fw, score], idx) => `  ${idx + 1}. ${fw.toUpperCase()}: ${score} points`);

console.log('\n═══════════════════════════════════════════');
console.log('  FRAMEWORK DECISION MATRIX — io.thecodeforge');
console.log('═══════════════════════════════════════════');
console.log('\nScores for your project constraints:');
console.log(ranked.join('\n'));

const winner = Object.entries(scores).sort(([, a], [, b]) => b - a)[0][0];
console.log(`\n→ Recommendation: ${winner.toUpperCase()}`);
console.log('\nNext step: document this decision in your ADR.');
console.log('Include: the constraint values above, the scores,');
console.log('and the explicit trade-offs you are accepting.');
console.log('The constraints matter more than the recommendation.\n');