convex-core

Convex のモデリングと関数作成の基本パターンです。このスキルは Convex で作業する際のデフォルトの基準です。 - **スキーマ**: https://docs.convex.dev/database/schemas - **データの読み取りとインデックス**: https://docs.convex.dev/database/reading-data/indexes - **バリデーション**: https://docs.convex.dev/functions/validation - **関数**: https://docs.convex.dev/functions - **ページネーション**: https://docs.convex.dev/database/pagination - **システムテーブル**: https://docs.convex.dev/database/advanced/system-tables - スキーマ: `convex/schema.ts` で `defineSchema`／`defineTable` を使用します。バリデーターには `v` を使用します。 - オプション: `schemaValidation: false` は実行時バリデーションを無効にします。`strictTableNameTypes: false` は TS の型で未宣言のテーブルを許可します。 - バリデーション: クエリ／ミューテーション／アクションには `args`／`returns` バリデーターを使用します。オブジェクトでは余分なプロパティは拒否されます。`undefined` は無効です（`null` を使用してください）。 - 判別可能なユニオン: 型安全な状態／種別の定義には、`as const` とともに `v.union` および `v.literal` を使用します。 - 型: 64 ビット整数には `v.bigint()` ではなく `v.int64()` を使用します。明示的に null を返す場合は `v.null()` を使用します。 - ID: 生の文字列の代わりに `Id<"table">` と `v.id("table")` を使用します。 - レコード: `v.record(keys, values)` のキーは ASCII で空でなく、`_` または `$` で始まってはなりません。 - バリデーターの合成: オブジェクトバリデーターでは `Infer`、`.pick`、`.omit`、`.extend`、`.partial` を使用できます。

スキーマのルール

• すべてのテーブルは、convex/schema.ts で defineSchema／defineTable を使用して定義しなければなりません。
• システムフィールド: _id（v.id(tableName)）と _creationTime（v.number()）は自動的に追加されます。
• すべてのフィールドに v.* バリデーターを使用しなければなりません。必要な場合を除き、v.any() の使用は避けるべきです。
• インデックスの命名: 名前にはすべてのフィールドを含めます。例: "by_field1_and_field2"。
• インデックスのルール:
  • .index(name, [fields...]) を使用しなければなりません。
  • フィールドの順序は重要です。範囲式はインデックスの順序に従わなければなりません。
  • 上限: インデックスあたり 16 フィールド、テーブルあたり 32 インデックスです。

関数のルール

• args、returns、handler を含む新しい関数構文を使用しなければなりません。
• HTTP アクションを除き、常に args と returns を検証しなければなりません。
• 読み取りには query、書き込みには mutation、外部処理や長時間実行する処理には action を使用します。
• アクションから ctx.db にアクセスしてはなりません。ctx.runQuery／ctx.runMutation を使用しなければなりません。
• 循環依存: 同じファイル内の関数を ctx.run* で呼び出す場合、受け取り側の変数に明示的な戻り値の型注釈を付けなければなりません。

データベース操作

• ctx.db.get、ctx.db.patch、ctx.db.replace、ctx.db.delete の第 1 引数には、テーブル名を明示しなければなりません。
• 置換: ドキュメント全体の置換には ctx.db.replace を使用します（対象が存在しない場合はエラーになります）。
• パッチ: 浅いマージによる更新には ctx.db.patch を使用します（対象が存在しない場合はエラーになります）。
• 削除: Convex のクエリは .delete() をサポートしていません。結果に .collect() を適用し、反復処理で ctx.db.delete(id) を呼び出さなければなりません。
• 一意性: ドキュメントを 1 件だけ取得するには .unique() を使用します。複数のドキュメントが一致した場合は必ずエラーになります。
• 本番環境のクエリでは filter を使用してはなりません。インデックスと .withIndex を使用します。

TypeScript のベストプラクティス

• 判別可能なユニオンでは、文字列リテラルに as const を使用しなければなりません。
• 配列は const array: Array<T> = [...]、レコードは const record: Record<K, V> = {...} として定義しなければなりません。
• すべてのドキュメント識別子には、string よりも Id<"table"> を優先しなければなりません。

クエリのパフォーマンス

• 大きなテーブルでは .filter より .withIndex を優先するべきです。
• 範囲指定なしで .withIndex を使用する場合、take、first、unique、paginate のいずれかと必ず組み合わせなければなりません。
• 検索の上限: 1024 件を超えるドキュメントに対して collect() を呼び出すとエラーになります。大きなデータセットには take(n)、paginate()、または for await による反復処理を使用するべきです。
• 非同期反復: 大きな結果セットをストリーミングする場合は、.collect() ではなく for await (const row of query) を使用します。

ページネーション

• args では paginationOptsValidator を必ず使用してください。
• .paginate() は { page, isDone, continueCursor } を返します。
• ページはリアクティブです。サイズは変更される可能性があります。
• .paginate() の戻り値オブジェクト全体に対して厳密な returns バリデーターを使用することは避けてください。page を検証するか、v.any() を使用してください。

クライアントのパターン

• convex/_generated/api の api.* 参照を必ず使用してください。
• React フック：useQuery、useMutation、useAction、usePaginatedQuery。
• レンダリング中にミューテーションやアクションを呼び出してはいけません。

安全性

• 関数ごとに必ず認証を適用してください。ctx.auth ヘルパーを使用して ID を確認してください。
• 公開関数で機密性の高いロジックを公開してはいけません。必ず内部関数を使用してください。