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を付けて保存する方法が向いています。

保存前から削除後までの変化を試す

  1. 共通教材(ZIP)をダウンロードして新しいフォルダーに展開します。Node.js と VS Code の用意がまだの方は、先にパソコンの準備を済ませてください。教材の基準は Node.js 24.22.1 で、この例は 26.13.1 でも動作を確認しました。
  2. VS Code の「ファイル → フォルダーを開く」で、emdash-technical-labs の中の publish-check を選びます。左側に src と tests の2つのフォルダーが並んでいることを確かめます。
  3. 「ターミナル → 新しいターミナル」を選びます。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」を置くキーです。

公式の参照元

関連ガイド

メニュー
ホーム公式ドキュメント (別タブで開く)

キーワードを入力すると、ガイドの内容から探せます。