ctx.kv で値を保存・取得・削除する
最後に扱った記事のIDなど、小さな値をプラグインに記録するときの書き方です。まだ値がないときや、同じ名前で保存し直したときの結果も手元で試せます。
目次
「最後に保存した記事のID」のように、プラグインが次回も使いたい値は ctx.kv に記録できます。ctx は、EmDash がプラグインの処理に渡してくれる道具一式です。その中の kv は、名前(キー)を付けて値を保存する場所です。プラグインごとに分かれていて、他のプラグインが同じキー名を使っても別々の値になります。
目的から操作を選ぶ
| やりたいこと | 呼び方 | 結果 |
|---|---|---|
| 値を読む | await ctx.kv.get(key) | 保存した値。キーがなければ null |
| 新しく保存する、または置き換える | await ctx.kv.set(key, value) | 同じキーを読むと新しい値が返る |
| 削除する | await ctx.kv.delete(key) | 削除できたら true。キーがなければ false |
過去の値を全部残したいときは、毎回同じキーに保存すると前の値が消えます。例えば「最後に保存した記事」を知りたいなら同じキーで更新し、「いつ、どの記事を保存したか」という履歴が欲しいなら、記録ごとにIDを付けて保存する方法が向いています。
保存前から削除後までの変化を試す
- 共通教材(ZIP)をダウンロードして新しいフォルダーに展開します。Node.js と VS Code の用意がまだの方は、先にパソコンの準備を済ませてください。教材の基準は Node.js 24.22.1 で、この例は 26.13.1 でも動作を確認しました。
- VS Code の「ファイル → フォルダーを開く」で、
emdash-technical-labsの中のpublish-checkを選びます。左側にsrcとtestsの2つのフォルダーが並んでいることを確かめます。 - 「ターミナル → 新しいターミナル」を選びます。Windows ではコマンドプロンプトを選んでください。次のコマンドで、テストに使う部品をそろえます。初回はインターネットに接続して実行してください。
npm ci今回はテスト用の EmDash がデータの保存先を用意します。練習サイトの管理画面へのログインや、記事の作成は不要です。
1. 値の変化を返す処理を足す
src の中の plugin.ts を開き、routes: { の次の行、既存の 'editor/summary' の直前に、以下を挿入して保存します。貼り付けたコードの最後の }, の次に、元の 'editor/summary': { が続きます。kv-demo は今回のテストが呼び出す処理の名前です。
'kv-demo': {
permission: 'plugins:manage',
handler: async (_request, ctx) => {
const key = 'practice:stage';
const before = await ctx.kv.get(key);
await ctx.kv.set(key, '下書き');
const saved = await ctx.kv.get(key);
await ctx.kv.set(key, '確認済み');
const updated = await ctx.kv.get(key);
const deleted = await ctx.kv.delete(key);
const after = await ctx.kv.get(key);
const deletedAgain = await ctx.kv.delete(key);
return { before, saved, updated, deleted, after, deletedAgain };
},
},await は、保存などの処理が済むまで次の行へ進まずに待つ書き方です。ここでは保存が済んでから読み、削除が済んでからもう一度読みます。
2. 実際に返った値を確かめる
src と並んでいる tests を開き、kv.test.ts を新しく作って次の内容で保存します。完成したファイルの位置は publish-check/tests/kv.test.ts です。このテストでは、actual に kv-demo が返した値が入ります。その下の toEqual に、期待する値を書きます。
import { createPluginTestHost } from '@emdash-cms/plugin-test';
import { expect, it } from 'vitest';
it('キーを作る前から削除した後までを確かめる', async () => {
const host = await createPluginTestHost();
try {
const actual = await host.invokeRoute('kv-demo');
expect(actual).toEqual({
before: null,
saved: '下書き',
updated: '確認済み',
deleted: true,
after: null,
deletedAgain: false,
});
} finally {
await host.dispose();
}
});publish-check のコマンド入力画面で、追加したテストだけを実行します。
npm test -- tests/kv.test.ts画面の最後に Tests 1 passed (1) と出れば、toEqual に書いた6個の値がすべて一致しています。テストコードを見直すと、saved は「下書き」、updated は「確認済み」です。同じキーに新しい値を保存できました。before と after はどちらも null です。保存前と削除後にはどちらもキーが存在しないことを示します。
予想した値と実際の値が違うと、テストはその項目で失敗します。例えばテストの deletedAgain を true に変えて再実行すると、実際には false だったことが表示されます。確かめたら false に戻してください。
教材でこの保存先を実際に使っているのが、記事を保存したときと公開したときのIDを記録する実習です。そこで登場する last-save は「最後に保存した記事のID」を置くキーです。