@exabugs/dynamodb-client 1.8.0 → 1.10.0

package/dist/server/utils/batchGet.js

@@ -0,0 +1,73 @@
+/**
+ * BatchGetItem の共通処理
+ *
+ * - 100 件ごとに分割する（BatchGetItem の上限）
+ * - スロットリング等で `UnprocessedKeys` が返ったら、指数バックオフで再試行して取りこぼさない
+ * - 再試行しても残る場合は、一部だけを返さずエラーにする（結果を壊さない）
+ */
+import { BatchGetCommand } from '@aws-sdk/lib-dynamodb';
+import { AppError, ErrorCode, createLogger } from '../../shared/index.js';
+import { executeDynamoDBOperation, getDBClient, getTableName } from './dynamodb.js';
+const logger = createLogger({
+    service: 'batch-get',
+    level: process.env.LOG_LEVEL || 'info',
+});
+/** BatchGetItem の 1 リクエストあたりのキー数の上限 */
+export const BATCH_GET_MAX_KEYS = 100;
+/** UnprocessedKeys の再試行回数の上限 */
+export const BATCH_GET_MAX_RETRIES = 8;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * キーに対応するレコードを全件取得する（重複キーは 1 回だけ取得する。順序は保証しない）
+ */
+export async function batchGetAll(keys, { consistentRead, costTracker, requestId, baseDelayMs = 50 }) {
+    const unique = Array.from(new Map(keys.map((k) => [`${k.PK}\u0000${k.SK}`, k])).values());
+    if (unique.length === 0) {
+        return [];
+    }
+    const dbClient = getDBClient();
+    const tableName = getTableName();
+    const records = [];
+    for (let i = 0; i < unique.length; i += BATCH_GET_MAX_KEYS) {
+        let pending = unique.slice(i, i + BATCH_GET_MAX_KEYS);
+        for (let attempt = 0; pending.length > 0; attempt++) {
+            if (attempt > BATCH_GET_MAX_RETRIES) {
+                // 一部だけを返すと、呼び出し側が「存在しない」と誤認する（更新・削除の対象から漏れる等）
+                logger.error('BatchGetItem の UnprocessedKeys が解消しなかった', {
+                    requestId,
+                    unprocessed: pending.length,
+                    attempts: attempt,
+                });
+                throw new AppError(ErrorCode.INTERNAL_ERROR, 'BatchGetItem still has unprocessed keys after retries', 503, { unprocessed: pending.length });
+            }
+            if (attempt > 0) {
+                await sleep(baseDelayMs * 2 ** (attempt - 1) * (0.5 + Math.random() / 2));
+            }
+            const keysToGet = pending;
+            const result = await executeDynamoDBOperation(() => dbClient.send(new BatchGetCommand({
+                RequestItems: {
+                    [tableName]: {
+                        Keys: keysToGet,
+                        ConsistentRead: consistentRead,
+                    },
+                },
+                ReturnConsumedCapacity: 'TOTAL',
+            })), 'BatchGetItem');
+            if (costTracker) {
+                const capacity = result.ConsumedCapacity;
+                if (Array.isArray(capacity)) {
+                    capacity.forEach((c) => costTracker.add(c));
+                }
+                else {
+                    costTracker.add(capacity);
+                }
+            }
+            records.push(...(result.Responses?.[tableName] ?? []));
+            pending = result.UnprocessedKeys?.[tableName]?.Keys ?? [];
+        }
+    }
+    return records;
+}
+//# sourceMappingURL=batchGet.js.map

package/dist/server/utils/batchGet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batchGet.js","sourceRoot":"","sources":["../../../src/server/utils/batchGet.ts"],"names":[],"mappings":"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"}

package/dist/server/utils/scanWarning.d.ts

@@ -0,0 +1,30 @@
+/** CloudWatch のメトリクスフィルタが検知するイベント名 */
+export declare const SPARSE_SCAN_EVENT = "SPARSE_SCAN";
+/** 閾値の既定値（1リクエストで読む件数） */
+export declare const DEFAULT_SCAN_WARN_THRESHOLD = 5000;
+/**
+ * 警告の閾値を取得する（環境変数 SCAN_WARN_THRESHOLD。1 以上の整数。不正な値は既定値）
+ */
+export declare function getScanWarnThreshold(): number;
+export interface ScanWatcherContext {
+    requestId: string;
+    resource: string;
+    /** 走査の種類（どの経路で疎な検索になったか） */
+    path: 'id-filtered-scan' | 'shadow-filter-first' | 'shadow-full-scan' | 'near-search';
+    sortField: string;
+    /** 絞り込みに使われたフィールドと演算子（例: "name:$contains"） */
+    filters: string[];
+}
+/**
+ * 1リクエスト内で読んだ件数を数え、閾値を超えたら警告を 1 回だけ記録する
+ */
+export declare class ScanWatcher {
+    private readonly context;
+    private scanned;
+    private warned;
+    private readonly threshold;
+    constructor(context: ScanWatcherContext);
+    /** 読んだ件数を加える */
+    add(count: number): void;
+}
+//# sourceMappingURL=scanWarning.d.ts.map

package/dist/server/utils/scanWarning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanWarning.d.ts","sourceRoot":"","sources":["../../../src/server/utils/scanWarning.ts"],"names":[],"mappings":"AAkBA,sCAAsC;AACtC,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAE/C,0BAA0B;AAC1B,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAO7C;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,4BAA4B;IAC5B,IAAI,EAAE,kBAAkB,GAAG,qBAAqB,GAAG,kBAAkB,GAAG,aAAa,CAAC;IACtF,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,WAAW;IAKV,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;gBAEvB,OAAO,EAAE,kBAAkB;IAExD,gBAAgB;IAChB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAqBzB"}

package/dist/server/utils/scanWarning.js

@@ -0,0 +1,63 @@
+/**
+ * 疎な検索（SPARSE_SCAN）の警告
+ *
+ * インデックス（シャドー）で絞り込めない条件の検索は、条件に一致する件数に対して
+ * 多くのレコードを読む必要がある。結果を正しく返すために途中で打ち切ることはせず、
+ * 1リクエストで読んだ件数が閾値を超えたときに警告を記録して、利用者が
+ * インデックス・スキーマ・ロジックの見直しに着手できるようにする。
+ *
+ * - 閾値: 環境変数 SCAN_WARN_THRESHOLD（1リクエストで読む件数。既定 5000）
+ * - 警告は 1 リクエストにつき 1 回、閾値を超えた時点で出す（Lambda がタイムアウトしても残る）
+ * - ログは JSON で `event: "SPARSE_SCAN"` を持つ。CloudWatch のメトリクスフィルタで検知できる
+ *   （terraform/ に定義済み。詳細は docs/SCAN_WARNING.md）
+ */
+import { createLogger } from '../../shared/index.js';
+// 警告は気づくための仕組みなので、LOG_LEVEL（error など）に関わらず必ず出力する
+const logger = createLogger({ service: 'scan-warning', level: 'warn' });
+/** CloudWatch のメトリクスフィルタが検知するイベント名 */
+export const SPARSE_SCAN_EVENT = 'SPARSE_SCAN';
+/** 閾値の既定値（1リクエストで読む件数） */
+export const DEFAULT_SCAN_WARN_THRESHOLD = 5000;
+/**
+ * 警告の閾値を取得する（環境変数 SCAN_WARN_THRESHOLD。1 以上の整数。不正な値は既定値）
+ */
+export function getScanWarnThreshold() {
+    const raw = process.env.SCAN_WARN_THRESHOLD;
+    if (raw === undefined || raw === '') {
+        return DEFAULT_SCAN_WARN_THRESHOLD;
+    }
+    const value = Number(raw);
+    return Number.isInteger(value) && value >= 1 ? value : DEFAULT_SCAN_WARN_THRESHOLD;
+}
+/**
+ * 1リクエスト内で読んだ件数を数え、閾値を超えたら警告を 1 回だけ記録する
+ */
+export class ScanWatcher {
+    context;
+    scanned = 0;
+    warned = false;
+    threshold = getScanWarnThreshold();
+    constructor(context) {
+        this.context = context;
+    }
+    /** 読んだ件数を加える */
+    add(count) {
+        this.scanned += count;
+        if (!this.warned && this.scanned >= this.threshold) {
+            this.warned = true;
+            logger.warn(`${SPARSE_SCAN_EVENT}: 1リクエストで ${this.scanned} 件以上を読みました。` +
+                `インデックス・スキーマ・ロジックの見直しを検討してください（docs/SCAN_WARNING.md）`, {
+                event: SPARSE_SCAN_EVENT,
+                ...this.context,
+                scanned: this.scanned,
+                threshold: this.threshold,
+                actions: [
+                    'インデックス: 絞り込みに使うフィールドをシャドー設定に追加し、$eq などインデックスで解決できる条件にする',
+                    'スキーマ: 絞り込み条件をキーにできるよう、コレクションの分割・非正規化を検討する',
+                    'ロジック: 絞り込みを毎回行う必要があるか、条件を変えられないか、結果をキャッシュできないかを見直す',
+                ],
+            });
+        }
+    }
+}
+//# sourceMappingURL=scanWarning.js.map

package/dist/server/utils/scanWarning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanWarning.js","sourceRoot":"","sources":["../../../src/server/utils/scanWarning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,iDAAiD;AACjD,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AAExE,sCAAsC;AACtC,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAE/C,0BAA0B;AAC1B,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;GAEG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IAC5C,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;QACpC,OAAO,2BAA2B,CAAC;IACrC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,2BAA2B,CAAC;AACrF,CAAC;AAYD;;GAEG;AACH,MAAM,OAAO,WAAW;IAKO;IAJrB,OAAO,GAAG,CAAC,CAAC;IACZ,MAAM,GAAG,KAAK,CAAC;IACN,SAAS,GAAG,oBAAoB,EAAE,CAAC;IAEpD,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAE5D,gBAAgB;IAChB,GAAG,CAAC,KAAa;QACf,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,MAAM,CAAC,IAAI,CACT,GAAG,iBAAiB,aAAa,IAAI,CAAC,OAAO,aAAa;gBACxD,qDAAqD,EACvD;gBACE,KAAK,EAAE,iBAAiB;gBACxB,GAAG,IAAI,CAAC,OAAO;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,OAAO,EAAE;oBACP,yDAAyD;oBACzD,2CAA2C;oBAC3C,oDAAoD;iBACrD;aACF,CACF,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/shared/utils/index.d.ts

@@ -5,4 +5,5 @@ export * from './logger.js';
 export * from './ulid.js';
 export * from './validation.js';
 export * from './dynamodb.js';
+export * from './scanSort.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/shared/utils/index.js

@@ -5,4 +5,5 @@ export * from './logger.js';
 export * from './ulid.js';
 export * from './validation.js';
 export * from './dynamodb.js';
+export * from './scanSort.js';
 //# sourceMappingURL=index.js.map

package/dist/shared/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shared/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shared/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC"}

package/dist/shared/utils/scanSort.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 全件読み取りの並べ替えフィールドを選ぶ
+ *
+ * フィルタが「単一フィールドの等価（$eq）で、値が短い普通の文字列」だけなら、そのフィールドを返す。
+ * シャドーのキー条件で一致するレコードだけを読めるので（O(一致件数)）、大きなコレクションでも
+ * 疎な検索（SPARSE_SCAN）にならない。それ以外は不変の `id`（カーソル方式。全件で O(件数)）。
+ *
+ * 数値・真偽値・長い文字列・日時形式の文字列は対象外。シャドーの SK は書き込み時に型ごとに変換される
+ * （数値はオフセット付き、真偽値は 1/0、日時形式の文字列は toISOString、長い文字列は
+ * SHADOW_STRING_MAX_BYTES で切り詰め）が、検索側の $eq は同じ変換をしないため、キー条件が一致せず
+ * 0 件になりうる（#57）。長さの上限はサーバー設定（既定 100 バイト）より十分小さい 64 バイトにしている。
+ *
+ * 注意: 読んでいる最中にそのフィールドの値が書き換わると取りこぼしうる（外部キーは通常変更されない）。
+ */
+export declare function chooseScanSortField(filter: Record<string, unknown>): string;
+//# sourceMappingURL=scanSort.d.ts.map

package/dist/shared/utils/scanSort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanSort.d.ts","sourceRoot":"","sources":["../../../src/shared/utils/scanSort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAkB3E"}

package/dist/shared/utils/scanSort.js

@@ -0,0 +1,33 @@
+/**
+ * 全件読み取りの並べ替えフィールドを選ぶ
+ *
+ * フィルタが「単一フィールドの等価（$eq）で、値が短い普通の文字列」だけなら、そのフィールドを返す。
+ * シャドーのキー条件で一致するレコードだけを読めるので（O(一致件数)）、大きなコレクションでも
+ * 疎な検索（SPARSE_SCAN）にならない。それ以外は不変の `id`（カーソル方式。全件で O(件数)）。
+ *
+ * 数値・真偽値・長い文字列・日時形式の文字列は対象外。シャドーの SK は書き込み時に型ごとに変換される
+ * （数値はオフセット付き、真偽値は 1/0、日時形式の文字列は toISOString、長い文字列は
+ * SHADOW_STRING_MAX_BYTES で切り詰め）が、検索側の $eq は同じ変換をしないため、キー条件が一致せず
+ * 0 件になりうる（#57）。長さの上限はサーバー設定（既定 100 バイト）より十分小さい 64 バイトにしている。
+ *
+ * 注意: 読んでいる最中にそのフィールドの値が書き換わると取りこぼしうる（外部キーは通常変更されない）。
+ */
+export function chooseScanSortField(filter) {
+    const keys = Object.keys(filter);
+    if (keys.length !== 1) {
+        return 'id';
+    }
+    const [key] = keys;
+    const value = filter[key];
+    const isPlainField = !key.includes(':') && !key.includes('.') && key !== 'id';
+    const isSafeString = typeof value === 'string' &&
+        value.length > 0 &&
+        new TextEncoder().encode(value).length <= 64 &&
+        // 空白や '#' はシャドーの SK でエスケープされ、'id' を含む値は SK の区切りと紛らわしくなる
+        // （extractRecordIds は最後の '#id#' で分けるが、念のため避ける）
+        !/[\s#]/.test(value) &&
+        value !== 'id' &&
+        !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value);
+    return isPlainField && isSafeString ? key : 'id';
+}
+//# sourceMappingURL=scanSort.js.map

package/dist/shared/utils/scanSort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scanSort.js","sourceRoot":"","sources":["../../../src/shared/utils/scanSort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA+B;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACnB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,MAAM,YAAY,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,IAAI,CAAC;IAC9E,MAAM,YAAY,GAChB,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,MAAM,GAAG,CAAC;QAChB,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,IAAI,EAAE;QAC5C,wDAAwD;QACxD,+CAA+C;QAC/C,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;QACpB,KAAK,KAAK,IAAI;QACd,CAAC,sCAAsC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtD,OAAO,YAAY,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC"}

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.8.0",
+  "version": "1.10.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"