Next.js: مكونات التخزين المؤقت و use cache

// app/dashboard/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function getUserData() {
  'use cache'
  cacheTag('user-data')
  cacheLife({ stale: 300, revalidate: 600 })

  const user = await db.user.findUnique({ where: { id: 1 } })  // تنفذ مرة واحدة فقط
  return user
}

export default async function DashboardPage() {
  const user = await getUserData()  // أول استدعاء ينفذ استعلام قاعدة البيانات
  // الاستدعاءات اللاحقة ستعيد النتيجة المخزنة مؤقتاً مباشرة

  return (
    <div>
      <UserAvatar user={user} />
      <UserGreeting user={user} />
      <UserStats user={user} />
      <UserNotifications user={user} />
    </div>
  )
}

// app/cache-demo/actions.ts
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

export async function getExpensiveData(id: string) {
  'use cache'
  cacheTag('expensive', `id-${id}`)         // الوسم
  cacheLife({ stale: 60, revalidate: 300 }) // إرجاع خلال 60 ثانية stale، إعادة المحاولة بعد 300 ثانية

  // جميع العمليات داخل هذه الدالة مخزنة مؤقتاً
  const result = await db.query(...)
  return result
}

يعرض واجهة مستخدم مكون getExpensiveData.

// app/cache-basic/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function getServerTime() {
  'use cache'
  cacheTag('server-time')
  cacheLife({ stale: 10, revalidate: 30 })

  // محاكاة عملية تستغرق وقتاً
  await new Promise(resolve => setTimeout(resolve, 1000))
  return { time: new Date().toISOString(), server: process.env.HOSTNAME ?? 'local' }
}

export default async function CacheBasicPage() {
  const [t1, t2, t3] = await Promise.all([
    getServerTime(),
    getServerTime(),
    getServerTime(),
  ])

  return (
    <div>
      <h1>use cache — أساسي</h1>
      <p>الاستدعاء 1: {t1.time}</p>
      <p>الاستدعاء 2: {t2.time}</p>
      <p>الاستدعاء 3: {t3.time}</p>
      <p><em>جميع الاستدعاءات الثلاثة أعادت نفس النتيجة المخزنة مؤقتاً (بدون حساب مكرر)</em></p>
    </div>
  )
}

الاستدعاء 1: 2026-07-06T10:00:00.000Z
الاستدعاء 2: 2026-07-06T10:00:00.000Z ← نفس الطابع الزمني (إصابة في التخزين المؤقت)
الاستدعاء 3: 2026-07-06T10:00:00.000Z ← نفس الطابع الزمني (إصابة في التخزين المؤقت)

الاستدعاء 1: 2026-07-06T10:00:00.000Z
الاستدعاء 2: 2026-07-06T10:00:00.000Z  ← تداخل بالميلي ثانية في التخزين المؤقت
الاستدعاء 3: 2026-07-06T10:00:00.000Z

// app/products/[id]/page.tsx
import { unstable_cacheTag as cacheTag } from 'next/cache'

export default async function ProductPage({ params }: { params: { id: string } }) {
  const product = await getProduct(params.id)
  return <ProductView product={product} />
}

async function getProduct(id: string) {
  'use cache'
  cacheTag('products', `product-${id}`)  // وسوم ديناميكية بناءً على المعاملات
  return fetch(`https://api.example.com/products/${id}`).then(r => r.json())
}

يجلب البيانات ويعرض النتيجة.

// app/cache-strategy/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

async function getUserProfile(userId: number) {
  'use cache'
  cacheTag('users', `user-${userId}`)
  cacheLife({ stale: 120, revalidate: 600 })  // دقيقتان stale، 10 دقائق revalidate
  return fetch(`https://jsonplaceholder.typicode.com/users/${userId}`).then(r => r.json())
}

async function getUserPosts(userId: number) {
  'use cache'
  cacheTag('posts', `user-posts-${userId}`)
  cacheLife({ stale: 60, revalidate: 300 })
  return fetch(`https://jsonplaceholder.typicode.com/users/${userId}/posts`).then(r => r.json())
}

export default async function CacheStrategyPage() {
  const [profile, posts] = await Promise.all([
    getUserProfile(1),
    getUserPosts(1),
  ])

  return (
    <div>
      <h1>{profile.name}</h1>
      <p>البريد الإلكتروني: {profile.email}</p>
      <h2>المقالات ({posts.length})</h2>
      <ul>{posts.map((p: any) => <li key={p.id}>{p.title}</li>)}</ul>
    </div>
  )
}

يجلب البيانات من جانب الخادم ويعرض قائمة بالعناصر.

يعرض المكون واجهة المستخدم الموصوفة في المتصفح.

// app/cache-invalidation/page.tsx
import { unstable_cacheTag as cacheTag, revalidateTag } from 'next/cache'

async function getTaskList() {
  'use cache'
  cacheTag('tasks')
  return fetch('https://jsonplaceholder.typicode.com/todos?_limit=5').then(r => r.json())
}

export default async function CacheInvalidationPage() {
  const tasks = await getTaskList()
  return (
    <div>
      <h1>قائمة المهام</h1>
      <ul>{tasks.map((t: any) => <li key={t.id}>{t.title}</li>)}</ul>
      <form action={async () => {
        'use server'
        revalidateTag('tasks')  // انقر الزر لتحديث التخزين المؤقت لقائمة المهام فوراً
      }}>
        <button type="submit">تحديث المهام</button>
      </form>
    </div>
  )
}

نموذج يحتوي على حقول إدخال وزر إرسال.
عند الإرسال، يقوم Server Action بمعالجة البيانات وإبطال وسوم التخزين المؤقت ذات الصلة.
النص المرئي: قائمة المهام

تعرض الصفحة كما هو موصوف أعلاه، مع تحديث واجهة المستخدم بناءً على السلوك الموصوف.

// app/cache-combo/page.tsx
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

// 1. التخزين المؤقت لـ fetch: استدعاء API خارجي
async function getExternalPosts() {
  return fetch('https://jsonplaceholder.typicode.com/posts', {
    next: { tags: ['external-posts'], revalidate: 300 }
  }).then(r => r.json())
}

// 2. use cache: معالجة البيانات
async function getProcessedPosts() {
  'use cache'
  cacheTag('processed-posts')
  cacheLife({ stale: 60, revalidate: 600 })

  const raw = await getExternalPosts()  // يعتمد على التخزين المؤقت لـ fetch
  return (raw as any[]).map((p: any) => ({
    id: p.id,
    title: p.title.toUpperCase(),
    summary: p.body.slice(0, 100),
  }))
}

export default async function CacheComboPage() {
  const posts = await getProcessedPosts()

  return (
    <div>
      <h1>المقالات المعالجة ({posts.length})</h1>
      <ul>{posts.map((p: any) => (
        <li key={p.id}><strong>{p.title}</strong><p>{p.summary}</p></li>
      ))}</ul>
    </div>
  )
}

يجلب البيانات من جانب الخادم ويعرض قائمة بالعناصر.

// app/cache-system/page.tsx — بنية تخزين مؤقت كاملة
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

// ======== طبقة البيانات (تخزين مؤقت صريح use cache) ========
type User = { id: number; name: string; email: string }
type Post = { id: number; title: string; body: string }

async function getUsers(): Promise<User[]> {
  'use cache'
  cacheTag('users')
  cacheLife({ stale: 120, revalidate: 600 })
  return fetch('https://jsonplaceholder.typicode.com/users').then(r => r.json())
}

async function getUserPosts(userId: number): Promise<Post[]> {
  'use cache'
  cacheTag('posts', `user-posts-${userId}`)
  cacheLife({ stale: 60, revalidate: 300 })
  return fetch(`https://jsonplaceholder.typicode.com/users/${userId}/posts`).then(r => r.json())
}

async function getStats(users: User[]) {
  'use cache'
  cacheTag('stats')
  cacheLife({ stale: 300, revalidate: 1800 })
  return {
    totalUsers: users.length,
    avgNameLength: users.reduce((s, u) => s + u.name.length, 0) / users.length,
  }
}

// ======== مكونات الصفحة ========
export default async function CacheSystemPage() {
  const users = await getUsers()
  const stats = await getStats(users)

  return (
    <div style={{ maxWidth: 900, margin: '0 auto', padding: 24 }}>
      <h1>إدارة المستخدمين</h1>
      <StatsCard stats={stats} />
      <div style={{ display: 'grid', gap: 16, marginTop: 24 }}>
        {users.map(user => (
          <UserCard key={user.id} user={user} />
        ))}
      </div>
    </div>
  )
}

// ======== المكون الفرعي (تخزين مؤقت مستقل) ========
async function UserCard({ user }: { user: User }) {
  const posts = await getUserPosts(user.id)
  return (
    <div style={{ border: '1px solid #ddd', borderRadius: 8, padding: 16 }}>
      <h2>{user.name}</h2>
      <p style={{ color: '#666' }}>{user.email}</p>
      <details>
        <summary>المقالات ({posts.length})</summary>
        <ul>{posts.map(p => <li key={p.id}>{p.title}</li>)}</ul>
      </details>
    </div>
  )
}

function StatsCard({ stats }: { stats: { totalUsers: number; avgNameLength: number } }) {
  return (
    <div style={{ background: '#f0f4ff', borderRadius: 8, padding: 16, display: 'flex', gap: 32 }}>
      <div><strong>إجمالي المستخدمين</strong><p style={{ fontSize: 24 }}>{stats.totalUsers}</p></div>
      <div><strong>متوسط طول الاسم</strong><p style={{ fontSize: 24 }}>{stats.avgNameLength.toFixed(1)}</p></div>
    </div>
  )
}

// ======== المهام الإدارية ========
// app/cache-system/actions.ts
'use server'
import { revalidateTag } from 'next/cache'

export async function refreshUserData() {
  revalidateTag('users')        // تحديث قائمة المستخدمين
}

export async function refreshPosts(userId: number) {
  revalidateTag(`user-posts-${userId}`)  // تحديث مقالات مستخدم محدد
}

export async function refreshAll() {
  revalidateTag('users')
  revalidateTag('posts')
  revalidateTag('stats')
}

// app/cache-system/admin-button.tsx
'use client'
export function AdminControls() {
  return (
    <div style={{ display: 'flex', gap: 8, margin: '16px 0' }}>
      <form action={async () => {
        const { refreshUserData } = await import('./actions')
        await refreshUserData()
      }}>
        <button type="submit">تحديث المستخدمين</button>
      </form>
      <form action={async () => {
        const { refreshAll } = await import('./actions')
        await refreshAll()
      }}>
        <button type="submit">تحديث الكل</button>
      </form>
    </div>
  )
}

نموذج يحتوي على حقول إدخال وزر إرسال.
عند الإرسال، يقوم Server Action بمعالجة البيانات وإبطال وسوم التخزين المؤقت ذات الصلة.
النص المرئي: إدارة المستخدمين

// app/cache-verify/page.tsx — التحقق مما إذا كانت هناك إصابة في التخزين المؤقت
import { unstable_cacheLife as cacheLife, unstable_cacheTag as cacheTag } from 'next/cache'

let callCount = 0

async function getUniqueId() {
  'use cache'
  cacheTag('unique-id')
  cacheLife({ revalidate: 30 })
  callCount++
  return { id: crypto.randomUUID(), calls: callCount }
}

export default async function CacheVerifyPage() {
  const [a, b, c] = await Promise.all([
    getUniqueId(),
    getUniqueId(),
    getUniqueId(),
  ])

  return (
    <div>
      <h1>التحقق من التخزين المؤقت</h1>
      <p>النتيجة أ: {a.id} (الاستدعاء #{a.calls})</p>
      <p>النتيجة ب: {b.id} (الاستدعاء #{b.calls})</p>
      <p>النتيجة ج: {c.id} (الاستدعاء #{c.calls})</p>
      <p><strong>نفس المعرف + calls = 1 → إصابة في التخزين المؤقت</strong></p>
    </div>
  )
}

المحتوى: التحقق من التخزين المؤقت | نفس المعرف + calls = 1 → إصابة في التخزين المؤقت

النتيجة أ: 550e8400-e29b-41d4-a716-446655440000 (الاستدعاء #1)
النتيجة ب: 550e8400-e29b-41d4-a716-446655440000 (الاستدعاء #1)  ← إصابة في التخزين المؤقت
النتيجة ج: 550e8400-e29b-41d4-a716-446655440000 (الاستدعاء #1)  ← إصابة في التخزين المؤقت