عامل satisfies في TypeScript 5.5 — الدليل الشامل للاستخدام والفوارق عن as

// 1. التعريف الصريح للنوع — يفقد معلومات النوع الدقيق
const palette: Record<string, string | number[]> = {
  red: [255, 0, 0],
  green: '#00ff00',
}
// الآن palette.red هو string | number[] وليس number[]

// 2. الاستنتاج التلقائي — لا تحقق من توافق النوع
const palette = {
  red: [255, 0, 0],
  green: '#00ff00',
}
// لا يوجد تحقق من توافق النوع مع Record<string, string | number[]>

const palette = {
  red: [255, 0, 0],
  green: '#00ff00',
} satisfies Record<string, string | number[]>

// الآن:
// - يتحقق TypeScript من توافق الكائن مع Record<string, string | number[]>
// - palette.red هو number[] (النوع الدقيق محفوظ)
// - palette.green هو string (النوع الدقيق محفوظ)
palette.red.map(v => v * 2)  // ✅ يعمل، red هو number[]
palette.green.toUpperCase()  // ✅ يعمل، green هو string

const value = 'hello' as number  // ✅ يمر TypeScript بدون خطأ
// لكن في وقت التشغيل سيكون 'hello' وليس رقمًا

// as يتجاوز فحص TypeScript — ينبغي استخدامه فقط حين تكون واثقًا تمامًا

const config: { mode: 'dark' | 'light' } = { mode: 'dark' }
// config.mode هو 'dark' | 'light' وليس 'dark' حصرًا
// فقدنا معرفة أن القيمة الفعلية هي 'dark'

const config = { mode: 'dark' } satisfies { mode: 'dark' | 'light' }
// config.mode هو 'dark' (النوع الحرفي محفوظ)
// يتحقق TypeScript من أن 'dark' يتوافق مع 'dark' | 'light'

const dbConfig = {
  host: 'localhost',
  port: 5432,
  ssl: true,
} satisfies {
  host: string
  port: number
  ssl?: boolean
}
// يُتحقق من التوافق مع هيكل الكائن
// لكن dbConfig.port هو 5432 (رقم حرفي) وليس number فقط

type Color = `#${string}` | [number, number, number]

const theme = {
  primary: '#3b82f6',
  secondary: [59, 130, 246],
  accent: '#6366f1',
} satisfies Record<string, Color>

// theme.primary هو '#3b82f6' (نوع حرفي دقيق)
// theme.secondary هو [number, number, number] (tuple)

type Lang = 'en' | 'ko' | 'ja'
type Translations = Record<Lang, { greeting: string; farewell: string }>

const messages = {
  en: { greeting: 'Hello', farewell: 'Goodbye' },
  ko: { greeting: 'Annyeonghaseyo', farewell: 'Annyeonghi gaseyo' },
  ja: { greeting: 'こんにちは', farewell: 'さようなら' },
} satisfies Translations

// TypeScript يتحقق من وجود جميع اللغات المطلوبة
// كل قيمة تحتفظ بنوعها الدقيق

const theme = {
  colors: {
    primary: '#3b82f6',
    success: '#10b981',
    warning: '#f59e0b',
    danger: '#ef4444',
  },
  spacing: {
    sm: 8,
    md: 16,
    lg: 24,
    xl: 32,
  },
} satisfies {
  colors: Record<string, `#${string}`>
  spacing: Record<string, number>
}

// theme.colors.primary هو '#3b82f6' تحديدًا
// theme.spacing.md هو 16 تحديدًا

const routes = {
  home: '/',
  blog: '/blog',
  tools: '/tools',
  about: '/about',
} satisfies Record<string, `/${string}`>

// TypeScript يتحقق من أن جميع المسارات تبدأ بـ /
// routes.home هو '/' (نوع حرفي دقيق)

type ApiResponse<T> = {
  data: T
  status: 200 | 201 | 400 | 404 | 500
  message: string
}

const userResponse = {
  data: { id: 1, name: 'Ahmed' },
  status: 200,
  message: 'Success',
} satisfies ApiResponse<{ id: number; name: string }>

// userResponse.status هو 200 (ليس 200 | 201 | 400 | 404 | 500)

// إذا كنت تريد قيمة النوع الأشمل للواجهة
function processConfig(config: Record<string, string | number>) {
  // ...
}

const myConfig: Record<string, string | number> = { port: 3000 }
// هنا التعريف الصريح للنوع أنسب من satisfies