تايب سكريبت و ستورج مانجر
تشرح هذه المقالة تايب سكريبت و ستورج مانجر۔
نقدم أمثلة عملية لشرح تايب سكريبت و ستورج مانجر۔
YouTube Video
تايب سكريبت و ستورج مانجر
ما هو ستورج مانجر؟
ستورج مانجر هو واجهة برمجة تطبيقات تتيح لتطبيقات الويب تقدير مقدار مساحة التخزين المستخدمة والمتوفرة۔ كما يوفر طلب الثبات (persist()) لمنع إزالة البيانات تلقائيًا من قبل المستخدم أو المتصفح۔ وهذا يسمح لك بالتحكم فيما إذا كانت هناك مساحة كافية متوفرة أو إذا كان سيتم حذف البيانات تلقائيًا، مثل عند تخزين كميات كبيرة من البيانات في IndexedDB للتطبيقات غير المتصلة بالإنترنت۔
الكشف عن الميزات
أولاً، تحقق ما إذا كان المتصفح يدعم navigator.storage۔
1// TypeScript: feature detection for StorageManager
2function supportsStorageManager(): boolean {
3 return typeof navigator !== "undefined" &&
4 typeof navigator.storage !== "undefined" &&
5 typeof navigator.storage.estimate === "function";
6}
7
8// Example usage
9if (supportsStorageManager()) {
10 console.log("StorageManager is supported.");
11} else {
12 console.warn("StorageManager not supported. Falling back to localStorage or IndexedDB.");
13}- تفحص هذه الوظيفة توفر واجهة برمجة تطبيقات ستورج مانجر على مراحل۔
- بما أن navigator.storage غير موجود في بعض المتصفحات مثل سفاري، من المهم التحقق من وجوده بأمان باستخدام typeof۔
تقدير استخدام مساحة التخزين (estimate())
بعد التحقق من الوظيفة باستخدام supportsStorageManager()، احصل على الاستخدام (usage) والحصة (quota) من navigator.storage.estimate().۔
1// TypeScript: safely get storage estimate
2async function getStorageEstimate(): Promise<{ usage: number; quota: number } | null> {
3 if (!supportsStorageManager()) {
4 console.warn("StorageManager not supported.");
5 return null;
6 }
7
8 const estimate = await navigator.storage.estimate();
9 return { usage: estimate.usage ?? 0, quota: estimate.quota ?? 0 };
10}
11
12// Example usage
13getStorageEstimate().then(result => {
14 if (result) {
15 console.log(`Usage: ${result.usage} bytes / Quota: ${result.quota} bytes`);
16 }
17});- تعمل هذه الوظيفة دائمًا بأمان وتعيد القيمة null إذا لم يدعمها المتصفح۔
- القيمتان usage و quota هما تقديرات وقد تختلفان من متصفح إلى آخر۔
طلب ثبات البيانات (persist())
استخدم persist() لطلب الثبات حتى لا تخضع البيانات المهمة (مثل الذاكرة المؤقتة بلا اتصال) للحذف التلقائي من قبل المتصفح۔ مع ذلك، قد لا ينجح في جميع البيئات۔
1// TypeScript: safely request persistent storage
2async function requestPersistence(): Promise<boolean> {
3 if (!supportsStorageManager()) {
4 console.warn("StorageManager not supported.");
5 return false;
6 }
7
8 if (typeof navigator.storage.persist !== "function") {
9 console.warn("persist() not available in this browser.");
10 return false;
11 }
12
13 try {
14 const granted = await navigator.storage.persist();
15 return Boolean(granted);
16 } catch (err) {
17 console.error("persist() error:", err);
18 return false;
19 }
20}
21
22// Example usage
23requestPersistence().then(granted => {
24 console.log("Persistence granted?", granted);
25});- إذا نجح persist() فلن يتم حذف البيانات تلقائياً من قبل المتصفح، إلا في حال تدخل المستخدم يدوياً۔ ومع ذلك، قد يتم رفض الطلبات اعتمادًا على إجراءات المستخدم أو إعدادات المتصفح۔
تحقق من السعة المتاحة قبل حفظ البيانات
تحقق من توفر المساحة قبل حفظ البيانات الكبيرة لتجنب فشل الكتابة (QuotaExceededError)۔
1// TypeScript: ensure enough space before writing
2async function ensureSpaceAndWrite(neededBytes: number, writeFn: () => Promise<void>): Promise<boolean> {
3 const estimate = await getStorageEstimate();
4 if (!estimate) {
5 console.warn("Cannot check storage space. Proceeding without validation.");
6 await writeFn();
7 return true;
8 }
9
10 const free = estimate.quota - estimate.usage;
11 if (free < neededBytes) {
12 console.warn(`Not enough space. Free: ${free} bytes, needed: ${neededBytes} bytes.`);
13 return false;
14 }
15
16 await writeFn();
17 return true;
18}
19
20// Example usage
21ensureSpaceAndWrite(10 * 1024 * 1024, async () => {
22 console.log("Saving large data...");
23});- من خلال التحقق من توفر التخزين قبل الحفظ، يمكنك تقليل خطر انقطاع الكتابة بسبب عدم كفاية السعة۔
التعامل مع localStorage بطريقة آمنة من حيث النوع في تايب سكريبت
localStorage مناسب لتخزين بيانات الإعدادات الخفيفة والمعلومات المشابهة۔
تستخدم الفئة التالية Generics لإنشاء غلاف آمن من حيث النوع۔
1// TypeScript: typed localStorage wrapper
2type Serializer<T> = {
3 serialize: (v: T) => string;
4 deserialize: (s: string) => T;
5};
6
7class TypedLocalStorage<K extends string, V> {
8 constructor(private storage: Storage, private serializer: Serializer<V>) {}
9
10 set(key: K, value: V): void {
11 this.storage.setItem(key, this.serializer.serialize(value));
12 }
13
14 get(key: K): V | null {
15 const raw = this.storage.getItem(key);
16 if (raw === null) return null;
17 try {
18 return this.serializer.deserialize(raw);
19 } catch {
20 return null;
21 }
22 }
23
24 remove(key: K): void {
25 this.storage.removeItem(key);
26 }
27
28 clear(): void {
29 this.storage.clear();
30 }
31}
32
33// Example usage
34const jsonSerializer: Serializer<any> = {
35 serialize: v => JSON.stringify(v),
36 deserialize: s => JSON.parse(s),
37};
38
39const appStorage = new TypedLocalStorage<'theme' | 'token', any>(localStorage, jsonSerializer);
40appStorage.set('theme', { dark: true });
41console.log(appStorage.get('theme'));- تساعد هذه الفئة في تقليل خطر تخزين أو استرجاع بيانات بنوع غير صحيح۔
اعتبارات عملية وأفضل الممارسات
-
تحقق دائماً ما إذا كان المتصفح يدعم ستورج مانجر نظرًا لأن ستورج مانجر هو واجهة برمجة تطبيقات جديدة نسبيًا، تحقق دائماً من وجوده قبل الاستخدام۔
-
انتبه لحدود التخزين والتوافق القيمة التي تعيدها estimate() تختلف حسب المتصفح وهي مجرد تقدير۔
-
صمّم مع وضع واجهات البرمجة غير المتزامنة في الحسبان estimate() و persist() هما واجهات برمجة تطبيقات غير متزامنة وتعتمدان على الوعود (Promises)۔ صمّم كودك بحيث لا تمنع واجهة المستخدم من العمل۔
-
اعتبارات الأمان لا تقم بتخزين معلومات حساسة مثل رموز الوصول في localStorage۔ فكّر في استخدام ملفات تعريف الارتباط HttpOnly أو التشفير إذا كان ذلك ممكنًا۔
-
تصميم بديل إذا أعاد supportsStorageManager() القيمة false، فعليك توفير منطق للتحول لاستخدام localStorage أو IndexedDB فقط۔
الملخص
من خلال الكشف عن الميزات باستخدام supportsStorageManager() يمكنك دعم جميع البيئات بأمان، والتحقق من الاستخدام والحصة عبر navigator.storage.estimate()، وطلب الثبات باستعمال persist()۔ في تايب سكريبت، استخدم الدوال المغلّفة وتعريفات الأنواع لكتابة كود قابل للقراءة وآمن. التدفق الأساسي هو: تحقق من الوجود، ثم التقدير، ثم طلب الثبات، ثم التحقق من السعة قبل الكتابة إلى التخزين۔
يمكنك متابعة المقالة أعلاه باستخدام Visual Studio Code على قناتنا على YouTube.۔ يرجى التحقق من القناة على YouTube أيضًا.۔