@exabugs/dynamodb-client 1.7.0 → 1.9.0

package/docs/README.md

@@ -0,0 +1,286 @@
+# @exabugs/dynamodb-client
+
+DynamoDB Single-Table設計向けのクライアントライブラリ。MongoDB風のAPIでDynamoDBを操作できます。
+
+## 特徴
+
+- **認証方式別クライアント**: IAM、Cognito、Token認証に最適化
+- **型安全**: TypeScriptで完全に型付けされたAPI
+- **軽量**: 認証方式ごとに必要な依存関係のみを含む
+- **MongoDB風API**: 使いやすいCRUD操作
+
+## インストール
+
+```bash
+npm install @exabugs/dynamodb-client
+# または
+pnpm add @exabugs/dynamodb-client
+```
+
+## クイックスタート
+
+### Cognito認証（ブラウザ/Node.js）
+
+```typescript
+import { DynamoClient } from '@exabugs/dynamodb-client/client/cognito';
+
+const client = new DynamoClient(FUNCTION_URL, {
+  auth: {
+    getToken: async () => {
+      // Cognitoトークンを取得
+      return token;
+    },
+  },
+});
+
+await client.connect();
+
+const db = client.db('mydb');
+const articles = db.collection('articles');
+
+// CRUD操作
+const results = await articles
+  .find({ status: 'published' })
+  .sort({ publishedAt: 'desc' })
+  .limit(10)
+  .toArray();
+```
+
+### IAM認証（Lambda/Node.js）
+
+```typescript
+import { DynamoClient } from '@exabugs/dynamodb-client/client/iam';
+
+const client = new DynamoClient(FUNCTION_URL, {
+  auth: {
+    region: process.env.AWS_REGION!,
+  },
+});
+
+await client.connect();
+
+const db = client.db('mydb');
+const articles = db.collection('articles');
+
+await articles.insertOne({
+  title: 'New Article',
+  status: 'draft',
+});
+```
+
+### Token認証（固定トークン）
+
+```typescript
+import { DynamoClient } from '@exabugs/dynamodb-client/client/token';
+
+const client = new DynamoClient(FUNCTION_URL, {
+  auth: {
+    token: 'your-static-token',
+  },
+});
+
+await client.connect();
+```
+
+## Records Lambda（サーバー側実装）
+
+このライブラリには、Records Lambda（サーバー側実装）も含まれています。
+
+### デプロイ方法
+
+Terraformモジュールを使用してデプロイします。
+
+```hcl
+module "lambda_records" {
+  source = "github.com/your-org/dynamodb-client//packages/core/terraform"
+  # または
+  # source = "../packages/core/terraform"  # ローカル開発時
+
+  project_name = "my-project"
+  environment  = "dev"
+  region       = "us-east-1"
+
+  # DynamoDB設定
+  dynamodb_table_name = "my-table"
+  dynamodb_table_arn  = "arn:aws:dynamodb:..."
+
+  # Cognito設定
+  cognito_user_pool_id = "us-east-1_xxxxx"
+
+  # シャドウ設定（base64エンコード）
+  shadow_config = base64encode(file("shadow.config.json"))
+}
+```
+
+### ビルド
+
+```bash
+cd packages/core
+pnpm build        # クライアントとサーバーの両方をビルド
+pnpm build:lambda # サーバーのみをビルド
+```
+
+詳細は[TerraformモジュールのREADME](./terraform/README.md)を参照してください。
+
+## メンテナンススクリプト
+
+### シャドーレコード修復
+
+DynamoClient（IAM認証）を使用してシャドーレコードを修復するスクリプトです。
+
+```bash
+# Dry run（変更なし）
+pnpm repair-shadows -- --resource articles --dry-run
+
+# 単一レコードを修復
+pnpm repair-shadows -- --resource articles --id <RECORD_ID> --repair
+
+# 全レコードを修復
+pnpm repair-shadows -- --resource articles --repair
+```
+
+環境変数:
+
+- `ENV`: 環境（dev/stg/prd）、デフォルト: `dev`
+- `AWS_REGION`: AWSリージョン、デフォルト: `us-east-1`
+- `RECORDS_API_URL`: Records Lambda Function URL（省略時はAWS CLIで自動取得）
+
+## ドキュメント
+
+- [使用ガイド](./CLIENT_USAGE.md) - 認証方式別の詳細な使用方法
+- [アーキテクチャ](./ARCHITECTURE.md) - 内部設計とコンポーネント構成
+
+## API型定義
+
+Records Lambda API の型定義は `@exabugs/dynamodb-client/types` からエクスポートされています。
+
+```typescript
+import type {
+  ApiErrorResponse, // 操作タイプ
+  ApiOperation, // リクエスト型
+  ApiRequest,
+  ApiResponse, // レスポンス型
+  ApiSuccessResponse,
+  BulkOperationResult,
+  DeleteOneParams,
+  FindManyParams,
+  FindOneParams,
+  FindParams, // データ型
+  FindResult,
+  InsertOneParams,
+  OperationError,
+  UpdateOneParams,
+} from '@exabugs/dynamodb-client/types';
+```
+
+## シャドウ管理機能
+
+このライブラリには、DynamoDB Single-Table設計におけるシャドウレコード管理機能が含まれています。
+
+### インストール
+
+```bash
+pnpm add @exabugs/dynamodb-client
+```
+
+### 使用方法
+
+#### シャドウSK生成
+
+```typescript
+import { generateShadowSK } from '@exabugs/dynamodb-client/shadows';
+
+// 文字列フィールド
+const nameSK = generateShadowSK('name', 'Tech News', '01HZXY123', 'string');
+// => 'name#Tech#News#id#01HZXY123'
+
+// 数値フィールド
+const prioritySK = generateShadowSK('priority', 123, '01HZXY123', 'number');
+// => 'priority#00000000000000000123#id#01HZXY123'
+
+// 日時フィールド
+const createdAtSK = generateShadowSK(
+  'createdAt',
+  '2025-11-12T10:00:00.000Z',
+  '01HZXY123',
+  'datetime'
+);
+// => 'createdAt#2025-11-12T10:00:00.000Z#id#01HZXY123'
+```
+
+#### シャドウ差分計算
+
+```typescript
+import { calculateShadowDiff } from '@exabugs/dynamodb-client/shadows';
+
+const oldKeys = ['name#Old#Name#id#01HZXY123', 'priority#00000000000000000010#id#01HZXY123'];
+
+const newKeys = ['name#New#Name#id#01HZXY123', 'priority#00000000000000000010#id#01HZXY123'];
+
+const diff = calculateShadowDiff(oldKeys, newKeys);
+// => {
+//   toDelete: ['name#Old#Name#id#01HZXY123'],
+//   toAdd: ['name#New#Name#id#01HZXY123']
+// }
+```
+
+#### 設定管理
+
+v0.3.x以降、shadow.config.jsonファイルは不要になりました。すべてのフィールドが自動的にシャドウ化されます。
+
+環境変数で動作をカスタマイズできます：
+
+```typescript
+// 環境変数（デフォルト値）
+process.env.SHADOW_CREATED_AT_FIELD = 'createdAt'; // 作成日時フィールド名
+process.env.SHADOW_UPDATED_AT_FIELD = 'updatedAt'; // 更新日時フィールド名
+process.env.SHADOW_STRING_MAX_BYTES = '100'; // 文字列の最大バイト数
+process.env.SHADOW_NUMBER_PADDING = '15'; // 数値のパディング桁数
+```
+
+シャドウレコードの生成例：
+
+```typescript
+import { generateShadowSK } from '@exabugs/dynamodb-client/shadows';
+
+// 各フィールドタイプのシャドウSK生成
+const nameSK = generateShadowSK('name', 'Tech News', '01HZXY123', 'string');
+// => 'name#Tech#News#id#01HZXY123'
+
+const prioritySK = generateShadowSK('priority', 123, '01HZXY123', 'number');
+// => 'priority#00000000000000000123#id#01HZXY123'
+
+const dateSK = generateShadowSK('createdAt', '2025-11-12T10:00:00.000Z', '01HZXY123', 'datetime');
+// => 'createdAt#2025-11-12T10:00:00.000Z#id#01HZXY123'
+```
+
+### エスケープルール
+
+文字列値は以下のルールでエスケープされます：
+
+- `#` → `##`
+- スペース → `#`
+
+例：
+
+- `"Tech News"` → `"Tech#News"`
+- `"AI#ML"` → `"AI##ML"`
+
+## パッケージ構成
+
+| エクスポート                              | 環境    | 用途                           | バンドルサイズ |
+| ----------------------------------------- | ------- | ------------------------------ | -------------- |
+| `@exabugs/dynamodb-client/client/iam`     | Node.js | IAM認証クライアント            | ~500KB         |
+| `@exabugs/dynamodb-client/client/cognito` | 共通    | Cognito認証クライアント        | ~50KB          |
+| `@exabugs/dynamodb-client/client/token`   | 共通    | Token認証クライアント          | ~50KB          |
+| `@exabugs/dynamodb-client/server`         | Node.js | Records Lambda（サーバー実装） | ~1.2MB         |
+| `@exabugs/dynamodb-client/server/handler` | Node.js | Records Lambda ハンドラー      | ~1.2MB         |
+| `@exabugs/dynamodb-client/shadows`        | Node.js | シャドウ管理機能               | ~10KB          |
+| `@exabugs/dynamodb-client/types`          | 共通    | API型定義                      | -              |
+| `@exabugs/dynamodb-client/terraform`      | -       | Terraformモジュール            | -              |
+
+## ライセンス
+
+MIT License - 詳細は [LICENSE](LICENSE) ファイルを参照してください。
+
+Copyright (c) 2024 exabugs

package/docs/SCAN_WARNING.md

@@ -0,0 +1,81 @@
+# 疎な検索の警告（SPARSE_SCAN）と対応
+
+## 方針
+
+インデックス（シャドー）で絞り込めない条件の検索は、一致する件数に対して多くのレコードを読む必要がある。
+**結果を正しく返すため、検索を途中で打ち切ることはしない**（途中までを「全件」「最終ページ」として返すと、
+呼び出し側が結果を誤って扱い、データの欠落や関連の誤削除につながる）。
+
+代わりに、1リクエストで読んだ件数が閾値を超えたとき**警告を記録**する。警告に気づいて、
+インデックス・スキーマ・ロジックの見直しに着手することが目的。
+
+## 何が警告されるか
+
+Records Lambda が、次の経路で 1 リクエストあたりの読み取り件数を数える。
+
+| `path`                | どんな検索か                                                                                                                                                                                                                |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id-filtered-scan`    | `sort: id`（react-admin の既定）に **id 以外のフィールドの絞り込み**を付けた検索。演算子（`$eq` を含む）によらず、id 順に全件を読んでメモリで絞る                                                                           |
+| `shadow-filter-first` | 並べ替えフィールドとは別のフィールドを `$eq` で先に絞り（`schema.cardinality` が perPage/2 を超える場合のみ）、残りの条件をメモリで絞る検索。全件をメモリに載せる                                                           |
+| `shadow-full-scan`    | 並べ替えフィールド以外への絞り込みで、`schema.cardinality` が未設定／小さい `$eq`、または `$contains` `$ne` `$in` `$regex` など（並べ替えフィールド自身へのこれらの演算子も含む）。並べ替えフィールドの全件をメモリに載せる |
+
+閾値は環境変数 `SCAN_WARN_THRESHOLD`（既定 5000 件）。Terraform では `scan_warn_threshold`。
+閾値に達した時点で 1 リクエストにつき 1 回、次の JSON を `warn` で出す（Lambda がタイムアウトしても残る）。
+
+```json
+{
+  "level": "warn",
+  "event": "SPARSE_SCAN",
+  "resource": "venues",
+  "path": "id-filtered-scan",
+  "sortField": "id",
+  "filters": ["name:$contains"],
+  "scanned": 5000,
+  "threshold": 5000,
+  "requestId": "…",
+  "actions": ["インデックス: …", "スキーマ: …", "ロジック: …"]
+}
+```
+
+クライアントの `toArrayAll()` も、100 ページ（既定。`warnPages` で変更）を超えるとコンソールに警告する。
+こちらも取得は打ち切らない。`maxPages` を**明示した**場合のみ、超過時にエラーを投げる（黙って切り詰めない）。
+
+## 警告に気づく
+
+`terraform/` を使っている場合、`event = "SPARSE_SCAN"` のログをメトリクス
+`<project>/<env>/Records` の `SparseScanCount` にし、CloudWatch アラーム
+`<project>-<env>-records-sparse-scan` を作る。通知するには `scan_warning_alarm_actions` に
+SNS トピックの ARN を渡す。Terraform を使わない場合は、同じ条件でメトリクスフィルタを作る。
+
+```text
+{ $.event = "SPARSE_SCAN" }
+```
+
+## 警告が出たら
+
+ログの `resource` / `path` / `filters` / `sortField` から、どの検索かを特定して見直す。
+
+1. **インデックスを見直す**
+   - 全フィールドは自動でシャドー（インデックス）化されている。効くかどうかは**並べ替えフィールドと演算子**で決まる
+   - **絞り込みに使うフィールドで並べ替える。** 並べ替えフィールドへの `$eq` `$gt` `$gte` `$lt` `$lte` `$starts` は、キー条件として直接読み取れる。`sort: id` とフィルタの組み合わせ（`id-filtered-scan`）は、どの演算子でも全件走査になるので避ける
+   - 並べ替えと別のフィールドを `$eq` で絞る場合は、`schema.cardinality` にそのフィールドの値の種類数を設定する（perPage/2 を超えると、そのフィールドで先に絞る filter-first が使われる）
+   - `$contains` `$ne` `$in` `$regex` などはインデックスを使えない。`$eq` / `$starts` / 範囲に置き換えられないか検討する
+2. **スキーマを見直す**
+   - 絞り込み条件で値を分けられるなら、コレクションを分ける、または条件を値に持つ別フィールド（検索用の接頭辞付きの値など）を追加する（非正規化）
+   - 多対多の中間テーブルなど、関連が増え続ける構造は、片側を並べ替えフィールドにして絞れる形にする
+3. **ロジックを見直す**
+   - その絞り込みを毎回行う必要があるか、条件を変えられないか、結果をキャッシュできないかを確認する
+   - 全件が必要な処理（バッチ・修復スクリプトなど）は、管理画面や API の通常経路ではなく、
+     `sort({ id: 'asc' }).toArrayAll()`（id 順のカーソル方式。全件で O(件数)）を使うバッチとして分ける。
+     オフセット方式の経路（`shadow-*`）で `toArrayAll` を使うと、ページごとに全件を読み直すため読み取り量が件数の二乗になる
+
+見直した後は、同じ検索で警告が出なくなったことをログで確認する。閾値は、
+アプリの通常の最大データ量に合わせて調整してよい（上げて警告を黙らせるのではなく、見直しを優先する）。
+
+## 補足
+
+- 警告は `LOG_LEVEL` に関わらず出力される（`LOG_LEVEL=error` でも出る）
+- `scan_warning_alarm_actions` が空のままだと、アラーム状態が記録されるだけで誰にも通知されない。
+  気づくためには SNS トピックなどの通知先を渡すこと
+- アラームとメトリクスの作成には、デプロイ用ロールに `logs:PutMetricFilter` `cloudwatch:PutMetricAlarm`
+  `cloudwatch:TagResource` が必要

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -38,6 +38,7 @@
     "bin",
     "dist",
     "terraform",
+    "docs/SCAN_WARNING.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/terraform/README.md

@@ -82,12 +82,14 @@ module "lambda_records" {
 
 ### オプション変数
 
-| 変数名               | 型     | デフォルト値 | 説明                                |
-| -------------------- | ------ | ------------ | ----------------------------------- |
-| `log_retention_days` | number | 7            | CloudWatch Logsの保持期間（日）     |
-| `log_level`          | string | "info"       | ログレベル（debug/info/warn/error） |
-| `lambda_timeout`     | number | 900          | Lambda関数のタイムアウト（秒）      |
-| `lambda_memory`      | number | 512          | Lambda関数のメモリサイズ（MB）      |
+| 変数名                       | 型           | デフォルト値 | 説明                                                                                                   |
+| ---------------------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------ |
+| `log_retention_days`         | number       | 7            | CloudWatch Logsの保持期間（日）                                                                        |
+| `log_level`                  | string       | "info"       | ログレベル（debug/info/warn/error）                                                                    |
+| `scan_warn_threshold`        | number       | 5000         | 疎な検索(SPARSE_SCAN)の警告を出す閾値（1リクエストで読む件数）。打ち切りはしない。docs/SCAN_WARNING.md |
+| `scan_warning_alarm_actions` | list(string) | []           | SPARSE_SCAN アラームの通知先（SNS トピック ARN）。空だと誰にも通知されない                             |
+| `lambda_timeout`             | number       | 900          | Lambda関数のタイムアウト（秒）                                                                         |
+| `lambda_memory`              | number       | 512          | Lambda関数のメモリサイズ（MB）                                                                         |
 
 ## 出力
 

package/terraform/main.tf

@@ -80,6 +80,43 @@ resource "aws_cloudwatch_log_group" "lambda_records" {
   }
 }
 
+# 疎な検索（SPARSE_SCAN）の警告を検知する
+# Lambda は、1リクエストで読んだ件数が SCAN_WARN_THRESHOLD を超えると event=SPARSE_SCAN の警告ログを出す。
+# 結果を壊さないため検索は打ち切らない。警告に気づいて、インデックス・スキーマ・ロジックの
+# 見直しに着手できるよう、メトリクスとアラームにする（対応手順: docs/SCAN_WARNING.md）
+resource "aws_cloudwatch_log_metric_filter" "sparse_scan" {
+  name           = "${var.project_name}-${var.environment}-records-sparse-scan"
+  log_group_name = aws_cloudwatch_log_group.lambda_records.name
+  pattern        = "{ $.event = \"SPARSE_SCAN\" }"
+
+  metric_transformation {
+    name          = "SparseScanCount"
+    namespace     = "${var.project_name}/${var.environment}/Records"
+    value         = "1"
+    default_value = "0"
+  }
+}
+
+resource "aws_cloudwatch_metric_alarm" "sparse_scan" {
+  alarm_name          = "${var.project_name}-${var.environment}-records-sparse-scan"
+  alarm_description   = "疎な検索(SPARSE_SCAN)の警告が出ています。ログの actions に従って、インデックス・スキーマ・ロジックを見直してください（docs/SCAN_WARNING.md）"
+  namespace           = aws_cloudwatch_log_metric_filter.sparse_scan.metric_transformation[0].namespace
+  metric_name         = aws_cloudwatch_log_metric_filter.sparse_scan.metric_transformation[0].name
+  statistic           = "Sum"
+  period              = 300
+  evaluation_periods  = 1
+  threshold           = 1
+  comparison_operator = "GreaterThanOrEqualToThreshold"
+  treat_missing_data  = "notBreaching"
+
+  alarm_actions = var.scan_warning_alarm_actions
+  ok_actions    = var.scan_warning_alarm_actions
+
+  tags = {
+    Name = "${var.project_name}-${var.environment}-records-sparse-scan"
+  }
+}
+
 # Lambda関数のZIPファイルを作成
 data "archive_file" "lambda_records" {
   type        = "zip"
@@ -118,6 +155,8 @@ resource "aws_lambda_function" "records" {
       COGNITO_USER_POOL_ID = var.cognito_user_pool_id
       COGNITO_CLIENT_ID    = var.cognito_client_id
       LOG_LEVEL            = var.log_level
+      # 疎な検索(SPARSE_SCAN)の警告閾値（1リクエストで読む件数）
+      SCAN_WARN_THRESHOLD = var.scan_warn_threshold
       # シャドウ設定（環境変数ベース）
       SHADOW_CREATED_AT_FIELD = var.shadow_created_at_field
       SHADOW_UPDATED_AT_FIELD = var.shadow_updated_at_field
@@ -215,7 +254,7 @@ module "parameter_store" {
   records_iam_function_url = aws_lambda_function_url.records_iam.function_url
   # IAM URL は常に同じ apply で作るため true を明示する（未確定の値の有無で count を決めない）
   create_records_iam_url_parameter = true
-  records_function_arn     = aws_lambda_function.records.arn
+  records_function_arn             = aws_lambda_function.records.arn
 
   # Cognito設定
   cognito_user_pool_id = var.cognito_user_pool_id

package/terraform/outputs.tf

@@ -59,3 +59,16 @@ output "iam_alias_arn" {
   description = "AWS_IAM認証用エイリアスのARN。呼び出し元IAMロールのlambda:InvokeFunctionUrl権限のResourceに指定する"
   value       = aws_lambda_alias.iam.arn
 }
+
+output "sparse_scan_alarm_name" {
+  description = "疎な検索(SPARSE_SCAN)の CloudWatch アラーム名"
+  value       = aws_cloudwatch_metric_alarm.sparse_scan.alarm_name
+}
+
+output "sparse_scan_metric" {
+  description = "疎な検索(SPARSE_SCAN)のメトリクス（namespace / name）"
+  value = {
+    namespace = aws_cloudwatch_log_metric_filter.sparse_scan.metric_transformation[0].namespace
+    name      = aws_cloudwatch_log_metric_filter.sparse_scan.metric_transformation[0].name
+  }
+}

package/terraform/variables.tf

@@ -55,6 +55,23 @@ variable "log_level" {
   }
 }
 
+variable "scan_warn_threshold" {
+  description = "疎な検索(SPARSE_SCAN)の警告を出す閾値（1リクエストで読むレコード件数）。超えても検索は打ち切らず、警告のみ記録する"
+  type        = number
+  default     = 5000
+
+  validation {
+    condition     = var.scan_warn_threshold >= 1 && floor(var.scan_warn_threshold) == var.scan_warn_threshold
+    error_message = "scan_warn_threshold は 1 以上の整数である必要があります。"
+  }
+}
+
+variable "scan_warning_alarm_actions" {
+  description = "SPARSE_SCAN アラームの通知先（SNS トピック ARN の配列）。空ならアラーム状態の記録のみ"
+  type        = list(string)
+  default     = []
+}
+
 # シャドウ設定（環境変数ベース）
 variable "shadow_created_at_field" {
   description = "作成日時フィールド名"