Ekstensi

Ekstensi adalah plug-in host yang melampirkan state miliknya sendiri ke runtime Nu. Ekstensi memungkinkan Anda menyimpan state editor, konfigurasi plug-in, atau data spesifik-host apa pun di samping dokumen. State sebuah ekstensi terbagi dua: state serializable berada di dalam dokumen — sehingga ikut serta dalam riwayat dan kolaborasi — sedangkan state volatile berada di luar dokumen dan tidak pernah dipersistensi.

Mendefinisikan ekstensi

Anda mendefinisikan ekstensi dengan createExtension, memberinya key unik, mendeklarasikan state awalnya, dan secara opsional menyediakan hook init dan dispose. Daftarkan ekstensi pada runtime melalui Nu.create, lalu baca kembali dengan nu.getExtension.

import { createExtension, Nu } from '@nuforge/core';
import * as t from '@nuforge/types';

const counter = createExtension<{ count: number; volatile: { ticks: number } }>({
  key: 'counter',
  state: { count: 0, volatile: { ticks: 0 } },
  init(ext) {
    // setup; read/write ext.state.count and ext.state.volatile.ticks
  },
  dispose(ext) {},
});

const nu = Nu.create({ extensions: [counter] });
nu.load(t.state({ program: t.program({}) }));

const ext = nu.getExtension(counter);

Parameter tipe mendeskripsikan bentuk dari state ekstensi. Hook init berjalan ketika ekstensi disiapkan dan merupakan tempat Anda merangkai segalanya; dispose berjalan saat pembongkaran.

State serializable

Apa pun di bawah state kecuali key volatile bersifat serializable. State tersebut disimpan di dalam AST pada state.extensions[<key>].value, sehingga ikut serta dalam undo/redo dan kolaborasi sama seperti data dokumen lainnya. Karena merupakan bagian dari dokumen, Anda harus memutasinya di dalam nu.change:

nu.change(() => {
  ext.state.count = 5; // persisted + undoable + synced
});

Penulisan itu dipersistensi di dalam dokumen, dicatat sebagai langkah yang dapat di-undo, dan disinkronkan ke kolaborator.

State volatile

Sub-objek volatile adalah pengecualian: ia berada di nu.volatile[<key>] dan tidak pernah diserialisasi. Gunakan untuk data sementara di luar dokumen — cache, flag UI transien, penghitung — yang seharusnya tidak dipersistensi, di-undo, atau disinkronkan. Anda memutasinya secara langsung, tanpa nu.change:

ext.state.volatile.ticks++; // off-document, ephemeral

Berlangganan perubahan

Untuk merespons saat state ekstensi berubah, gunakan ext.subscribe. Anda memberikan sebuah collector yang memilih nilai yang Anda pedulikan dan sebuah callback yang berjalan setiap kali nilai terkumpul itu berubah.

const dispose = ext.subscribe(
  (state) => state.count,
  (count, prev) => {
    // runs when the collected value changes
  },
);

Fungsi pertama mengumpulkan sebuah nilai dari state ekstensi; fungsi kedua berjalan dengan nilai baru dan sebelumnya setiap kali nilai terkumpul itu berubah. Panggil dispose yang dikembalikan untuk berhenti mendengarkan.

Riwayat

Penyiapan ekstensi dikecualikan dari riwayat. Memuat dokumen yang mendaftarkan ekstensi tidak membuat langkah undo — hanya penulisan yang Anda lakukan kemudian di dalam nu.change yang dicatat. Hal ini menjaga tumpukan undo tetap bersih dan terfokus pada editan yang bermakna bagi pengguna.

Langkah berikutnya

• Runtime & Core API — objek Nu, mutasi, dan riwayat.
• Collaboration — bagaimana state serializable disinkronkan antar peer.