convex-mutations

Convex ミューテーションスキル

このスキルでは、関数の定義、登録、データベース操作、スケジューリングのパターンに関するベストプラクティスなど、Convex のミューテーション関数の実装に特化したガイダンスを提供します。

このスキルを使う場面

次のような場合に、このスキルを使用します。

• Convex データベース内のデータを書き込んだり変更したりする新しいミューテーション関数を定義する場合
• データベース操作（insert、patch、replace、delete）を実行する場合
• 他の Convex 関数からミューテーションを呼び出す場合
• ctx.scheduler.runAfter で将来のミューテーションをスケジュールする場合
• トランザクション操作を処理する場合
• バックグラウンド処理のためにミューテーションとアクションを連携させる場合

スキルのリソース

このスキルには、以下を網羅した包括的なリファレンスドキュメント references/mutation-guidelines.md が含まれています。

ミューテーション開発の基本

• 新しい関数構文を使った関数定義の構文
• ミューテーションの登録（mutation と internalMutation）
• 引数バリデーターとその使用方法
• 関数の呼び出しパターン（ctx.runQuery と ctx.runMutation）
• 関数参照（api オブジェクトと internal オブジェクト）
• ミューテーションのパスに対するファイルベースのルーティング

データベース操作

• ctx.db.insert() - 新しいドキュメントを作成します
• ctx.db.patch() - 既存のドキュメントに浅いマージで変更を適用します
• ctx.db.replace() - 既存のドキュメントを完全に置き換えます
• ドキュメントが見つからない場合のエラー処理
• トランザクションのセマンティクスと一貫性の保証

高度なミューテーション機能

• スケジューリング：ctx.scheduler.runAfter() を使ってバックグラウンドジョブをキューに追加します
  • 将来実行するミューテーションやアクションをスケジュールします
  • 認証状態はスケジュールされたジョブに引き継がれないことを理解します
  • 特権が必要なスケジュール済みジョブには内部関数を使用します
  • 短い間隔でのループを避け、最小間隔の 10 秒を守ります
• トランザクションの動作：ミューテーションのトランザクションを理解します
  • スケジューラージョブのキューへの追加は、ミューテーション内でトランザクションとして処理されます
  • トランザクション境界によって競合状態を防ぎます

関数の合成

• 検証のためにミューテーション内でクエリを呼び出します
• ミューテーション内で別のミューテーションを呼び出します
• 同じファイル内のミューテーション呼び出しに戻り値の型注釈を使用します

このスキルの使い方

1. リファレンスドキュメント references/mutation-guidelines.md を読み、ミューテーションのパターンをすべて理解します
2. 構文例に従い、適切なバリデーターを使ってミューテーション関数を定義します
3. ニーズに応じて適切なデータベース操作（insert、patch、replace）を使用します
4. 実行時間の長い処理には、ctx.scheduler.runAfter を使ってバックグラウンド処理をスケジュールします
5. 認証状態はスケジュールされたジョブに引き継がれないことを忘れず、特権操作には内部関数を使用します
6. 複数の操作にわたる一貫性を保つために、トランザクションを活用します

ミューテーションの主なガイドライン

• すべてのミューテーション関数に、必ず引数バリデーターを含めます
• 部分更新には ctx.db.patch() を、完全な置き換えには ctx.db.replace() を使用します
• アクション（AI の応答や通知など）のスケジュールには ctx.scheduler.runAfter() を使用します
• スケジュール済みジョブの認証状態は null です。代わりに内部関数を使用します
• ミューテーションの実行時間は最大 1 秒で、最大 8192 件のドキュメントを書き込めます
• 明示的な戻り値がない場合、ミューテーションは暗黙的に null を返します
• 同じファイル内でミューテーションを呼び出す場合は、戻り値の型注釈を使用します（TypeScript の循環性への対処策）

例：データベース操作とスケジューリングを伴うミューテーション

import { mutation, internalAction } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";

export const sendMessage = mutation({
  args: {
    channelId: v.id("channels"),
    authorId: v.id("users"),
    content: v.string(),
  },
  handler: async (ctx, args) => {
    // Validate channel and user exist
    const channel = await ctx.db.get(args.channelId);
    if (!channel) {
      throw new Error("Channel not found");
    }

    // Insert message into database
    await ctx.db.insert("messages", {
      channelId: args.channelId,
      authorId: args.authorId,
      content: args.content,
    });

    // Schedule AI response generation (transactional)
    await ctx.scheduler.runAfter(0, internal.functions.generateResponse, {
      channelId: args.channelId,
    });

    return null;
  },
});

export const updateUserStatus = mutation({
  args: {
    userId: v.id("users"),
    status: v.string(),
  },
  handler: async (ctx, args) => {
    // Patch updates an existing document with shallow merge
    await ctx.db.patch(args.userId, {
      status: args.status,
      lastUpdated: Date.now(),
    });
    return null;
  },
});

詳しい情報やその他のパターンについては、リファレンスドキュメント全体を参照してください。