@exabugs/dynamodb-client 1.15.0 → 1.16.0

package/docs/RECORDS_CLIENT.md

@@ -0,0 +1,45 @@
+# Records クライアントのヘルパー
+
+Lambda などのサーバー側から Records（IAM 版 Function URL）を呼ぶ定型を、ライブラリが持つ（[ADR 0006](adr/0006-library-owns-table-operations.md)）。`@exabugs/dynamodb-client/client/iam` から import する。
+
+| 関数                                 | 用途                                                                                         |
+| ------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `createRecordsClient(options?)`      | `DynamoClient` の生成と `connect()`。`connect()` の呼び忘れを防ぐ                            |
+| `withCollection(name, fn, options?)` | 作る → `fn(collection)` → 確実に close。Lambda の 1 回の呼び出しで使い切る                   |
+| `lazyCollection(name, options?)`     | 最初の使用時に 1 回だけ接続し、コンテナ内で再利用。失敗はキャッシュしない。`.reset()` で破棄 |
+| `createAdminDirectory(options?)`     | `@exabugs/dynamodb-client/notify`。`admins` の全件から通知の宛先（メール）を返す             |
+
+`options`: `url`（省略時は環境変数 `RECORDS_IAM_URL`）、`region`（省略時は `AWS_REGION`、無ければ `REGION`）、`timeout`（ms。Records の Lambda の timeout より短くする）。
+
+`createAdminDirectory` の主なオプション: `recipientFields`（宛先を取るフィールド。既定 `['id']`、`['email','id']` で `email ?? id`）、`maxAdmins`（既定 200。件数が超えたら例外、ちょうどは成功）、`sortById`（id 昇順で読む）、`source`（`authorizedCollection` の `list` と同じ形。権限チェック層を通すアプリが渡す。指定すると自前で接続しない）。
+
+## Lambda での使い方
+
+コンテナで使い回す（コールドスタートで 1 回だけ接続）:
+
+```ts
+import { lazyCollection } from '@exabugs/dynamodb-client/client/iam';
+
+const venues = lazyCollection<VenueRecord>('venues', { timeout: 15_000 });
+
+export const handler = async () => {
+  const active = await (await venues()).find({ status: 'active' }).toArray();
+  // ...
+};
+```
+
+呼び出しごとに使い切る:
+
+```ts
+import { withCollection } from '@exabugs/dynamodb-client/client/iam';
+
+await withCollection<WeatherRecord>('weather', (weather) =>
+  weather.updateOne({ id }, { $set: data }, { upsert: true })
+);
+```
+
+asanowa の `functions/weather` の `getDynamoClient`（`new DynamoClient` + `connect()` + `db()` のキャッシュ）は、`lazyCollection` の 1 行になる。
+
+## テスト
+
+`DynamoClient` を丸ごとモックすると `connect()` の呼び忘れを見逃す。本物の `DynamoClient` を使い、`fetch` だけ差し替える（`vi.stubGlobal('fetch', ...)`。例: `__tests__/client/recordsClient.test.ts`）。コレクションを差し替えたいときは、`lazyCollection` の戻り値の関数をアプリ側のモジュールに閉じ込め、そのモジュールをモックする。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exabugs/dynamodb-client",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "DynamoDB Single-Table Client SDK with MongoDB-like API, Shadow Records, and Lambda implementation for serverless applications",
   "author": "exabugs",
   "license": "MIT",
@@ -43,7 +43,8 @@
     "LICENSE",
     "CHANGELOG.md",
     "docs/NOTIFY.md",
-    "docs/DYNAMODB_ACCESS.md"
+    "docs/DYNAMODB_ACCESS.md",
+    "docs/RECORDS_CLIENT.md"
   ],
   "exports": {
     ".": {

package/terraform/media/README.md

@@ -39,8 +39,7 @@ module "media" {
   region       = "ap-northeast-1"
 
   # Records の IAM 版 Function URL とエイリアスの ARN（本体の出力）。media の Lambda は
-  # DynamoDB に直接触れず、Records を呼ぶ（ADR 0005）。table_name / table_arn / shadow_* は
-  # deprecated（1.16.0 で削除）で、渡しても無視される
+  # DynamoDB に直接触れず、Records を呼ぶ（ADR 0005）
   records_iam_function_url = module.records.iam_function_url
   records_iam_alias_arn = module.records.iam_alias_arn
 

package/terraform/media/variables.tf

@@ -36,18 +36,6 @@ variable "records_iam_alias_arn" {
   }
 }
 
-variable "table_name" {
-  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
-  type        = string
-  default     = ""
-}
-
-variable "table_arn" {
-  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
-  type        = string
-  default     = ""
-}
-
 variable "image_cache_ttl_days" {
   description = "cache/{fileId}/{width}（オンデマンドリサイズ結果）のS3 Lifecycleによる自動削除までの日数"
   type        = number
@@ -60,31 +48,6 @@ variable "allowed_upload_origins" {
   default     = []
 }
 
-# 以下の shadow_* は deprecated（1.16.0 で削除。ADR 0005）。Records 経由になったため無視される。
-variable "shadow_created_at_field" {
-  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
-  type        = string
-  default     = "createdAt"
-}
-
-variable "shadow_updated_at_field" {
-  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
-  type        = string
-  default     = "updatedAt"
-}
-
-variable "shadow_string_max_bytes" {
-  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
-  type        = number
-  default     = 100
-}
-
-variable "shadow_number_padding" {
-  description = "deprecated。1.16.0 で削除（ADR 0005）。media の Lambda は DynamoDB に直接触れなくなったため無視される。"
-  type        = number
-  default     = 15
-}
-
 variable "signing_public_key_param" {
   description = "CloudFront署名用の公開鍵（PEM形式）を保持するSSM Parameter名。値そのものは呼び出し側が別途登録する"
   type        = string