E EmDash CMS Everything Guides, use cases, plugins, templates
日本語

Storage

このページ

サンドボックス化されたプラグインは、独自のデータをドキュメントコレクションに保存できます。マニフェストでコレクションとインデックスを宣言すると、EmDashが自動的にスキーマを作成します。マイグレーションを書く必要はありません。

このページではサンドボックス化されたプラグインについて説明します。コレクションAPIはネイティブプラグインでも同じです。唯一の違いは、ネイティブプラグインがマニフェストではなくdefinePlugin()内でstorageを宣言することです。

マニフェストでのストレージの宣言

サンドボックス化されたプラグインの場合、storageはemdash-plugin.jsoncにあります。宣言はビルド時に可視である必要があり、サンドボックスブリッジがプラグインがアクセスできるコレクションを知るためです。

{
	"slug": "forms",
	// ...identity + profile...

	"storage": {
		"submissions": {
			"indexes": [
				"formId",
				"status",
				"createdAt",
				["formId", "createdAt"],
				["status", "createdAt"]
			]
		},
		"forms": {
			"indexes": ["slug"]
		}
	}
}

storageの各キーはコレクション名です。indexes配列は効率的にクエリできるフィールドをリストします。単一フィールドインデックスは文字列として、複合インデックスは文字列の配列として表されます。完全なルールについてはマニフェストリファレンスを参照してください。

実行時のストレージの使用

src/plugin.tsでは、ctx.storageを介してコレクションにアクセスします。形状はマニフェストで宣言されたものを反映しています：

import type { SandboxedPlugin } from "emdash/plugin";

export default {
	hooks: {
		"content:afterSave": {
			handler: async (event, ctx) => {
				const { submissions } = ctx.storage;

				await submissions.put("sub_123", {
					formId: "contact",
					email: "user@example.com",
					status: "pending",
					createdAt: new Date().toISOString(),
				});

				const item = await submissions.get("sub_123");
				ctx.log.info("Stored submission", { id: item?.formId });
			},
		},
	},
} satisfies SandboxedPlugin;

マニフェストで宣言されていないコレクションにアクセスするとエラーがスローされます。ブリッジは実行時レベルでこれを強制します。

コレクションAPI

interface StorageCollection<T = unknown> {
	// 基本的なCRUD
	get(id: string): Promise<T | null>;
	put(id: string, data: T): Promise<void>;
	delete(id: string): Promise<boolean>;
	exists(id: string): Promise<boolean>;

	// バッチ操作
	getMany(ids: string[]): Promise<Map<string, T>>;
	putMany(items: Array<{ id: string; data: T }>): Promise<void>;
	deleteMany(ids: string[]): Promise<number>;

	// クエリ（インデックス付きフィールドのみ）
	query(options?: QueryOptions): Promise<PaginatedResult<{ id: string; data: T }>>;
	count(where?: WhereClause): Promise<number>;
}

クエリ

query()はインデックス付きフィールドでフィルタリングされたページネーション結果を返します：

const result = await ctx.storage.submissions.query({
	where: {
		formId: "contact",
		status: "pending",
	},
	orderBy: { createdAt: "desc" },
	limit: 20,
});

// result.items   — Array<{ id, data }>
// result.cursor  — ページネーションカーソル（より多くの結果が存在する場合）
// result.hasMore — boolean

クエリオプション

interface QueryOptions {
	where?: WhereClause;
	orderBy?: Record<string, "asc" | "desc">;
	limit?: number;     // デフォルト50、最大1000
	cursor?: string;    // ページネーション用
}

Where句演算子

これらの演算子を使用してインデックス付きフィールドでフィルタリングします：

完全一致

where: {
	status: "pending",     // 文字列の完全一致
	count: 5,              // 数値の完全一致
	archived: false,       // ブール値の完全一致
}

範囲

where: {
	createdAt: { gte: "2024-01-01" },
	score: { gt: 50, lte: 100 },
}
// 利用可能: gt, gte, lt, lte

リスト内

where: {
	status: { in: ["pending", "approved"] },
}

前方一致

where: {
	slug: { startsWith: "blog-" },
}

ソート

orderBy: { createdAt: "desc" }   // 最新のものを最初に
orderBy: { score: "asc" }        // 最低のものを最初に

ページネーション

一致するすべてのアイテムを歩くためにカーソルを消費します：

async function getAllSubmissions(ctx: PluginContext) {
	const all: Array<{ id: string; data: unknown }> = [];
	let cursor: string | undefined;

	do {
		const result = await ctx.storage.submissions.query({
			orderBy: { createdAt: "desc" },
			limit: 100,
			cursor,
		});
		all.push(...result.items);
		cursor = result.cursor;
	} while (cursor);

	return all;
}

カウント

const total = await ctx.storage.submissions.count();

const pending = await ctx.storage.submissions.count({
	status: "pending",
});

バッチ操作

const items = await ctx.storage.submissions.getMany(["sub_1", "sub_2", "sub_3"]);
// Map<string, T>を返す

await ctx.storage.submissions.putMany([
	{ id: "sub_1", data: { formId: "contact", status: "new" } },
	{ id: "sub_2", data: { formId: "contact", status: "new" } },
]);

const deletedCount = await ctx.storage.submissions.deleteMany(["sub_1", "sub_2"]);

インデックス設計

実際のクエリパターンに基づいてインデックスを選択します：

クエリパターン必要なインデックス
formIdでフィルタ"formId"
formIdでフィルタ、createdAtでソート["formId", "createdAt"]
createdAtのみでソート"createdAt"
statusとformIdでフィルタ"status"と"formId"（別々）

複合インデックスは、最初のフィールドでフィルタリングし、オプションで2番目のフィールドでソートするクエリをサポートします：

// インデックス ["formId", "createdAt"] の場合:
query({ where: { formId: "contact" }, orderBy: { createdAt: "desc" } });  // インデックスを使用
query({ where: { formId: "contact" } });                                  // インデックスを使用（フィルタのみ）
query({ where: { createdAt: { gte: "2024-01-01" } } });                   // この複合インデックスは使用しない — フィルタが誤ったフィールドから始まる

型安全性

アイテムの形状についてIntelliSenseを得るためにコレクションアクセスをキャストします：

import type { SandboxedPlugin } from "emdash/plugin";
import type { StorageCollection } from "emdash";

interface Submission {
	formId: string;
	email: string;
	data: Record<string, unknown>;
	status: "pending" | "approved" | "spam";
	createdAt: string;
}

export default {
	hooks: {
		"content:afterSave": {
			handler: async (event, ctx) => {
				const submissions = ctx.storage.submissions as StorageCollection<Submission>;

				await submissions.put(`sub_${Date.now()}`, {
					formId: "contact",
					email: "user@example.com",
					data: { message: "Hello" },
					status: "pending",
					createdAt: new Date().toISOString(),
				});
			},
		},
	},
} satisfies SandboxedPlugin;

両方のインポートは型のみであるため、サンドボックス化されたプラグインはemdashへの実行時依存関係を持ちません。

Storage vs Content vs KV

各種類のデータに適したメカニズムを選択してください：

ユースケースストレージ
プラグインの運用データ（ログ、送信、キャッシュ）ctx.storage
ユーザー設定可能な設定ctx.kv（settings:プレフィックス）
内部プラグイン状態ctx.kv（state:プレフィックス）
管理UIで編集可能なコンテンツサイトコレクション（プラグインストレージではない）

サイトエディターが通常のコンテンツエディターを介して管理UIでデータを表示または編集する必要がある場合は、代わりにサイトコレクションを作成してください。

実装の詳細

プラグインストレージは単一の名前空間付きテーブルを使用します：

CREATE TABLE _plugin_storage (
	plugin_id TEXT NOT NULL,
	collection TEXT NOT NULL,
	id TEXT NOT NULL,
	data JSON NOT NULL,
	created_at TEXT,
	updated_at TEXT,
	PRIMARY KEY (plugin_id, collection, id)
);

EmDashは宣言されたフィールドに対して式インデックスを作成します：

CREATE INDEX idx_forms_submissions_formId
	ON _plugin_storage(json_extract(data, '$.formId'))
	WHERE plugin_id = 'forms' AND collection = 'submissions';

この設計により、マイグレーションなし、SQLite/libSQL/D1間の移植性、プラグインレベルの分離、およびすべてのパスでのパラメータ化されたクエリが提供されます。

インデックスの追加

プラグインの更新でインデックスを追加すると、EmDashは次回起動時に自動的に作成します。インデックスの追加は安全であり、データマイグレーションは必要ありません。インデックスを削除すると、EmDashはそれを削除します。そのフィールドへのクエリは検証エラーで失敗し始めます。これは意図された信号です。