ساحة التجربة

غيّر المدخلات. وشاهد كيف يستجيب restate.

سبع تجارب تشغّل الحزمة الحقيقية. المتحكم على اليسار يخص هذا الموقع؛ أما المثال على اليمين فلا يتلقى إلا props، لذا فشيفرته هي بالضبط ما ستكتبه أنت.

المتحكم — للموقع فقطprops — الجسرالمثال — الشيفرة التي تنسخها

شاشتان ومخزن واحد

تحتاج عدة مكوّنات إلى القيمة نفسها. عرّفها مرة واحدة واقرأها في أي مكان.

ما الذي تراقبه

اضغط زر الخطوة: يعرض كل القرّاء الرقم الجديد في اللحظة نفسها.
غيّر عدد القرّاء: يبدأ القارئ الجديد من القيمة الحالية.

المتحكمليس جزءًا من شيفرة المثال. تصل القيم إلى المثال على شكل props.

القرّاءreaders
الخطوةstep

<Example
  readers={3}
  step={1}
/>

جارٍ تجهيز المثال…

تحتاج الأمثلة الحية إلى JavaScript. يمكن قراءة الشيفرة أدناه كما هي.

App.jsx

import { restate } from '@kkwaenggwari/restate';
import './styles.css';

const useCount = restate(0);

function Reader({ name }) {
  const count = useCount();

  return (
    <section className="card">
      <span>{name}</span>
      <output>{count}</output>
    </section>
  );
}

export default function Example({ readers = 3, step = 1 }) {
  return (
    <main>
      <div className="grid">
        {Array.from({ length: readers }, (_, index) => (
          <Reader key={index} name={`الشاشة ${index + 1}`} />
        ))}
      </div>
      <div className="actions">
        <button onClick={() => useCount.set((count) => count + step)}>+{step}</button>
        <button onClick={() => useCount.reset()}>إعادة الضبط</button>
      </div>
    </main>
  );
}

البداية

اعرض ما تغيّر فقط

لا ينبغي لمخزن كبير أن يعيد عرض كل مكوّن عند كل تعديل.

ما الذي تراقبه

عدّل البطاقة: لا تُعرض إلا بطاقة المخزن الكامل.
أضف منتجًا: تُعرض المنتجات والملخص؛ وتبقى بطاقة القسيمة ثابتة.
أوقف shallow: يُعرض الملخص عند كل تعديل، لأن selector الخاص به يعيد كائنًا جديدًا في كل مرة.

المتحكمليس جزءًا من شيفرة المثال. تصل القيم إلى المثال على شكل props.

قارن الملخص عبر shallowshallowSummary

<Example
  shallowSummary={true}
/>

جارٍ تجهيز المثال…

تحتاج الأمثلة الحية إلى JavaScript. يمكن قراءة الشيفرة أدناه كما هي.

App.jsx

import { memo, useRef } from 'react';
import { restate, shallow } from '@kkwaenggwari/restate';
import './styles.css';

const useCart = restate({ items: ['Book'], coupon: '', note: '' });

function Card({ title, value }) {
  const renders = useRef(0);
  renders.current += 1;

  return (
    <section className="card">
      <span>{title}</span>
      <output>{value}</output>
      <small>{`${renders.current} مرة عرض`}</small>
    </section>
  );
}

const ItemCount = memo(function ItemCount() {
  const count = useCart((cart) => cart.items.length);
  return <Card title="المنتجات" value={count} />;
});

const Coupon = memo(function Coupon() {
  const coupon = useCart((cart) => cart.coupon);
  return <Card title="القسيمة" value={coupon || 'لا شيء'} />;
});

const Summary = memo(function Summary({ compare }) {
  const summary = useCart((cart) => ({ count: cart.items.length, coupon: cart.coupon }), compare);
  return <Card title="الملخص" value={`${summary.count} · ${summary.coupon || '-'}`} />;
});

const Whole = memo(function Whole() {
  const cart = useCart();
  return <Card title="المخزن الكامل" value={cart.note.length} />;
});

export default function Example({ shallowSummary = true }) {
  return (
    <main>
      <div className="grid">
        <ItemCount />
        <Coupon />
        <Summary compare={shallowSummary ? shallow : undefined} />
        <Whole />
      </div>
      <div className="actions">
        <button onClick={() => useCart.set((cart) => ({ ...cart, items: [...cart.items, 'Pen'] }))}>
          أضف منتجًا
        </button>
        <button
          onClick={() => useCart.set((cart) => ({ ...cart, coupon: cart.coupon ? '' : 'SPRING' }))}
        >
          بدّل القسيمة
        </button>
        <button onClick={() => useCart.set((cart) => ({ ...cart, note: cart.note + '!' }))}>
          عدّل البطاقة
        </button>
      </div>
    </main>
  );
}

اشترك فقط فيما تحتاجه

تغييرات كثيرة، إشعار واحد

تحديث مخزنين واحدًا تلو الآخر يتيح لمشترك أن يرى حالة نصف مكتملة.

ما الذي تراقبه

أفرغ كلًا على حدة: يرى المشترك 0 منتجات مع القسيمة القديمة.
أفرغ عبر batch: يعمل المشترك مرة واحدة، بعد أن يتغيّر المخزنان كلاهما.

المتحكمليس جزءًا من شيفرة المثال. تصل القيم إلى المثال على شكل props.

المنتجاتquantity
القسيمةcoupon

<Example
  quantity={3}
  coupon="SPRING"
/>

جارٍ تجهيز المثال…

تحتاج الأمثلة الحية إلى JavaScript. يمكن قراءة الشيفرة أدناه كما هي.

App.jsx

import { useEffect, useState } from 'react';
import { batch, restate } from '@kkwaenggwari/restate';
import './styles.css';

const useItems = restate([]);
const useCoupon = restate('');

export default function Example({ quantity = 3, coupon = 'SPRING' }) {
  const items = useItems();
  const code = useCoupon();
  const [notices, setNotices] = useState([]);

  useEffect(() => {
    useItems.set(Array.from({ length: quantity }, (_, index) => `#${index + 1}`));
    useCoupon.set(coupon);
    setNotices([]);
  }, [quantity, coupon]);

  useEffect(
    () =>
      useItems.subscribe((next) => {
        const notice = `إشعار: ${next.length} منتجات · القسيمة ${useCoupon.get() || '-'}`;
        setNotices((list) => [...list, notice]);
      }),
    [],
  );

  const clear = () => {
    useItems.set([]);
    useCoupon.set('');
  };

  return (
    <main>
      <div className="grid">
        <section className="card">
          <span>المنتجات</span>
          <output>{items.length}</output>
        </section>
        <section className="card">
          <span>القسيمة</span>
          <output>{code || '-'}</output>
        </section>
      </div>
      <div className="actions">
        <button onClick={clear}>أفرغ كلًا على حدة</button>
        <button onClick={() => batch(clear)}>أفرغ عبر batch</button>
      </div>
      <h2>ما رآه المشترك</h2>
      <ol className="log">
        {notices.length ? (
          notices.map((notice, index) => <li key={index}>{notice}</li>)
        ) : (
          <li>لا إشعارات بعد.</li>
        )}
      </ol>
    </main>
  );
}

اشترك فقط فيما تحتاجه

احفظ حين تقرّر

التعديل يغيّر الذاكرة. والحفظ إجراء صريح، والحالة تُظهر ما يجري.

ما الذي تراقبه

اكتب: يتفعّل dirty ولا يُكتب شيء بعد.
ارفع زمن الاستجابة واحفظ: يعرض operation القيمة save أثناء الكتابة.
أعد التشغيل: تُستعاد المسودة المحفوظة من IndexedDB.

المتحكمليس جزءًا من شيفرة المثال. تصل القيم إلى المثال على شكل props.

زمن استجابة التخزينlatency

<Example
  latency={600}
/>

جارٍ تجهيز المثال…

تحتاج الأمثلة الحية إلى JavaScript. يمكن قراءة الشيفرة أدناه كما هي.

App.jsx

import { useEffect } from 'react';
import { persistedRestate } from '@kkwaenggwari/restate';
import { settings, slowStorage } from './storage.js';
import './styles.css';

const useDraft = persistedRestate('', { key: 'playground-draft', storage: slowStorage });

export default function Example({ latency = 600 }) {
  useEffect(() => {
    settings.latency = latency;
  }, [latency]);

  const text = useDraft();
  const { dirty, operation, pending, lastSavedAt } = useDraft.useStatus();
  // A failed save keeps dirty and records status.error.
  const save = () => useDraft.save().catch(() => {});
  const revert = () => useDraft.restore().catch(() => {});

  return (
    <main>
      <label>
        المسودة
        <textarea value={text} onChange={(event) => useDraft.set(event.target.value)} />
      </label>
      <div className="actions">
        <button disabled={!dirty} onClick={save}>
          حفظ
        </button>
        <button disabled={!dirty} onClick={revert}>
          تجاهل التعديلات
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{dirty ? 'تعديلات غير محفوظة' : 'تم الحفظ'}</dd>
        <dt>operation</dt>
        <dd>{operation ?? 'لا شيء'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>lastSavedAt</dt>
        <dd>{lastSavedAt ? new Date(lastSavedAt).toLocaleTimeString() : 'ليس بعد'}</dd>
      </dl>
    </main>
  );
}

storage.js

import { createIndexedDBStorage } from '@kkwaenggwari/restate';

// IndexedDB with an adjustable delay, to watch operations in progress.
const indexedDB = createIndexedDBStorage();
export const settings = { latency: 0 };
const wait = () => new Promise((resolve) => setTimeout(resolve, settings.latency));

export const slowStorage = {
  async getItem(key) {
    await wait();
    return indexedDB.getItem(key);
  },
  async setItem(key, value) {
    await wait();
    return indexedDB.setItem(key, value);
  },
  async removeItem(key) {
    await wait();
    return indexedDB.removeItem(key);
  },
};

احفظ حين تقرّر

اكتب بسرعة، واكتب مرة واحدة

الحفظ عند كل ضغطة مفتاح يُغرق التخزين. ينتظر autoSave توقّفًا.

ما الذي تراقبه

اكتب جملة: ترتفع التعديلات بسرعة، بينما تزيد الكتابات بواحدة بعد كل توقّف.
اختر «عند كل تعديل»: كل تعديل يُكتب، لكن العودة إلى القيمة المحفوظة لا تكتب شيئًا.

المتحكمليس جزءًا من شيفرة المثال. تصل القيم إلى المثال على شكل props.

انتظار autoSavedelayMs

<Example
  delayMs={800}
/>

جارٍ تجهيز المثال…

تحتاج الأمثلة الحية إلى JavaScript. يمكن قراءة الشيفرة أدناه كما هي.

App.jsx

import { useState } from 'react';
import { persistedRestate, useRestateScope } from '@kkwaenggwari/restate';
import { countingStorage, useWrites } from './storage.js';
import './styles.css';

function Note({ delayMs }) {
  const useNote = useRestateScope((scope) =>
    persistedRestate('', {
      scope,
      key: 'note',
      storage: countingStorage,
      autoSave: delayMs ? { delayMs } : true,
    }),
  );
  const note = useNote();
  const dirty = useNote.useStatus((status) => status.dirty);
  const writes = useWrites();
  const [edits, setEdits] = useState(0);

  return (
    <>
      <label>
        ملاحظة
        <textarea
          value={note}
          placeholder="اكتب جملة بسرعة…"
          onChange={(event) => {
            useNote.set(event.target.value);
            setEdits((count) => count + 1);
          }}
        />
      </label>
      <div className="grid">
        <section className="card">
          <span>التعديلات</span>
          <output>{edits}</output>
        </section>
        <section className="card accent">
          <span>الكتابات إلى التخزين</span>
          <output>{writes}</output>
        </section>
      </div>
      <p className={dirty ? 'badge warn' : 'badge ok'}>{dirty ? 'بانتظار توقّف' : 'تم الحفظ'}</p>
    </>
  );
}

export default function Example({ delayMs = 800 }) {
  // autoSave is part of the declaration: a new delay starts a new scope.
  return (
    <main>
      <Note key={delayMs} delayMs={delayMs} />
    </main>
  );
}

storage.js

import { restate } from '@kkwaenggwari/restate';

// An in-memory storage adapter that counts real writes.
const records = new Map();
export const useWrites = restate(0);

export const countingStorage = {
  getItem: (key) => records.get(key) ?? null,
  setItem: (key, value) => {
    records.set(key, value);
    useWrites.set((count) => count + 1);
  },
  removeItem: (key) => {
    records.delete(key);
  },
};

احفظ حين تقرّر

مختبر الأعطال

اجعل التخزين بطيئًا أو معطّلًا أو غير متاح، وشاهد restate يحافظ على بياناتك ويُبلغ عن المشكلة.

ما الذي تراقبه

ارفع زمن الاستجابة واحفظ ثلاث مرات: تتشارك الطلبات كتابة واحدة، فيبقى pending عند 1 وتصل النتائج الثلاث معًا.
فعّل فشل الكتابات واحفظ: يبقى dirty على true ويعرض error السبب.
اجعل التخزين غير متاح: يُرفض الحفظ بـ STORAGE_UNAVAILABLE بينما يواصل التعديل عمله.

المتحكمليس جزءًا من شيفرة المثال. تصل القيم إلى المثال على شكل props.

زمن الاستجابةlatency
إفشال الكتاباتfailWrites
التخزين غير متاحunavailable

<Example
  latency={700}
  failWrites={false}
  unavailable={false}
/>

جارٍ تجهيز المثال…

تحتاج الأمثلة الحية إلى JavaScript. يمكن قراءة الشيفرة أدناه كما هي.

App.jsx

import { useEffect, useState } from 'react';
import { persistedRestate } from '@kkwaenggwari/restate';
import { flakyStorage, settings } from './storage.js';
import './styles.css';

const useNote = persistedRestate('', { key: 'lab-note', storage: flakyStorage });

export default function Example({ latency = 700, failWrites = false, unavailable = false }) {
  useEffect(() => {
    Object.assign(settings, { latency, failWrites, unavailable });
  }, [latency, failWrites, unavailable]);

  const note = useNote();
  const { dirty, operation, pending, error } = useNote.useStatus();
  const [results, setResults] = useState([]);

  const save = () =>
    useNote.save().then(
      (value) => setResults((list) => [`تم الحفظ: ${JSON.stringify(value)}`, ...list]),
      (reason) => setResults((list) => [`فشل: ${reason.code ?? reason.message}`, ...list]),
    );

  return (
    <main>
      <label>
        ملاحظة
        <input value={note} onChange={(event) => useNote.set(event.target.value)} />
      </label>
      <div className="actions">
        <button onClick={save}>حفظ</button>
        <button
          onClick={() => {
            save();
            save();
            save();
          }}
        >
          احفظ ثلاث مرات
        </button>
      </div>
      <dl className="status">
        <dt>dirty</dt>
        <dd className={dirty ? 'warn' : 'ok'}>{String(dirty)}</dd>
        <dt>operation</dt>
        <dd>{operation ?? '-'}</dd>
        <dt>pending</dt>
        <dd>{pending}</dd>
        <dt>error</dt>
        <dd className={error ? 'bad' : ''}>{error ? (error.code ?? error.message) : '-'}</dd>
      </dl>
      <h2>النتائج</h2>
      <ol className="log">
        {results.length ? (
          results.map((result, index) => <li key={results.length - index}>{result}</li>)
        ) : (
          <li>-</li>
        )}
      </ol>
    </main>
  );
}

storage.js

// A storage adapter whose speed and failures you can change.
const records = new Map();
export const settings = { latency: 0, failWrites: false, unavailable: false };
const wait = () => new Promise((resolve) => setTimeout(resolve, settings.latency));

export const flakyStorage = {
  isAvailable: () => !settings.unavailable,
  async getItem(key) {
    await wait();
    return records.get(key) ?? null;
  },
  async setItem(key, value) {
    await wait();
    if (settings.failWrites) throw new Error('القرص ممتلئ');
    records.set(key, value);
  },
  async removeItem(key) {
    await wait();
    records.delete(key);
  },
};

موثوقية by design

حالة لكل مستند

يحتاج كل مستند مفتوح إلى حالته الخاصة، وتُحرَّر عند إغلاق المستند.

ما الذي تراقبه

اكتب في المستند A ثم في B: يحتفظ كل منهما بنصه.
أغلق المستند A وأعد فتحه: يبدأ فارغًا، لأن نطاقه أُتلف.

المتحكمليس جزءًا من شيفرة المثال. تصل القيم إلى المثال على شكل props.

المستنداتdocuments
المستند A مفتوحfirstOpen

<Example
  documents={2}
  firstOpen={true}
/>

جارٍ تجهيز المثال…

تحتاج الأمثلة الحية إلى JavaScript. يمكن قراءة الشيفرة أدناه كما هي.

App.jsx

import { restate, useRestateScope } from '@kkwaenggwari/restate';
import './styles.css';

function Document({ name }) {
  const useText = useRestateScope((scope) => restate('', { scope }));
  const text = useText();

  return (
    <section className="card">
      <span>{name}</span>
      <input
        value={text}
        placeholder="مكتوب هنا فقط"
        onChange={(event) => useText.set(event.target.value)}
      />
      <small>{`${text.length} حرف`}</small>
    </section>
  );
}

export default function Example({ documents = 2, firstOpen = true }) {
  const names = ['A', 'B', 'C'].slice(0, documents);

  return (
    <main>
      <div className="grid">
        {names.map((name, index) =>
          index === 0 && !firstOpen ? null : <Document key={name} name={`المستند ${name}`} />,
        )}
      </div>
    </main>
  );
}

حالة يملكها مكوّن