@exabugs/dynamodb-client 0.1.0

package/dist/server/utils/chunking.js

@@ -0,0 +1,225 @@
+/**
+ * チャンク分割ユーティリティ
+ *
+ * DynamoDBのTransactWriteItemsは最大100アイテムまでしか処理できないため、
+ * バルク操作（createMany、updateMany、deleteMany）で大量のレコードを処理する際に
+ * チャンク分割が必要となる。
+ *
+ * 要件: 13.1, 13.2, 13.7, 13.8, 13.9
+ */
+import { createLogger } from '../../index.js';
+const logger = createLogger({ service: 'records-lambda' });
+/**
+ * DynamoDB TransactWriteItemsの最大アイテム数制限
+ *
+ * DynamoDBのTransactWriteItemsは最大100アイテムまでしか処理できない。
+ * この制限を超える場合は、複数のトランザクションに分割する必要がある。
+ *
+ * 参考: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html
+ */
+export const DYNAMODB_TRANSACT_WRITE_MAX_ITEMS = 100;
+/**
+ * バルク操作のチャンクサイズを動的に計算する
+ *
+ * 各レコードのアイテム数（メインレコード + シャドーレコード）を考慮して、
+ * TransactWriteItemsの100アイテム制限内に収まるようにチャンクを分割する。
+ *
+ * @param records - 処理対象のレコード配列
+ * @param getItemCount - 各レコードのアイテム数を計算する関数
+ * @returns チャンク分割結果
+ * @throws {Error} 単一レコードが100アイテムを超える場合
+ *
+ * @example
+ * ```typescript
+ * // createMany操作の例
+ * const result = calculateChunks(records, (record) => {
+ *   const shadowCount = calculateShadowCount(record);
+ *   return 1 + shadowCount; // メイン + シャドー
+ * });
+ *
+ * // updateMany操作の例
+ * const result = calculateChunks(records, (record) => {
+ *   const oldShadowCount = record.__shadowKeys?.length || 0;
+ *   const newShadowCount = calculateNewShadowCount(record);
+ *   return 1 + oldShadowCount + newShadowCount; // メイン + 削除 + 追加
+ * });
+ * ```
+ */
+export function calculateChunks(records, getItemCount) {
+    const chunks = [];
+    const itemCounts = [];
+    let currentChunk = [];
+    let currentItemCount = 0;
+    for (const record of records) {
+        const itemCount = getItemCount(record);
+        // 単一レコードがDynamoDB制限を超える場合はエラー
+        if (itemCount > DYNAMODB_TRANSACT_WRITE_MAX_ITEMS) {
+            const errorMsg = `Single record exceeds ${DYNAMODB_TRANSACT_WRITE_MAX_ITEMS} items limit: ${itemCount} items`;
+            logger.error('Chunk validation failed', {
+                itemCount,
+                limit: DYNAMODB_TRANSACT_WRITE_MAX_ITEMS,
+            });
+            throw new Error(errorMsg);
+        }
+        // 現在のチャンクに追加するとDynamoDB制限を超える場合、新しいチャンクを開始
+        if (currentItemCount + itemCount > DYNAMODB_TRANSACT_WRITE_MAX_ITEMS) {
+            if (currentChunk.length > 0) {
+                chunks.push(currentChunk);
+                itemCounts.push(currentItemCount);
+            }
+            currentChunk = [record];
+            currentItemCount = itemCount;
+        }
+        else {
+            currentChunk.push(record);
+            currentItemCount += itemCount;
+        }
+    }
+    // 最後のチャンクを追加
+    if (currentChunk.length > 0) {
+        chunks.push(currentChunk);
+        itemCounts.push(currentItemCount);
+    }
+    // 詳細なチャンク分割情報をログ出力
+    logger.info('Chunk calculation completed', {
+        totalRecords: records.length,
+        chunkCount: chunks.length,
+        itemCounts,
+        minItemsPerChunk: itemCounts.length > 0 ? Math.min(...itemCounts) : 0,
+        maxItemsPerChunk: itemCounts.length > 0 ? Math.max(...itemCounts) : 0,
+        avgItemsPerChunk: itemCounts.length > 0
+            ? Math.round(itemCounts.reduce((sum, count) => sum + count, 0) / itemCounts.length)
+            : 0,
+    });
+    return { chunks, itemCounts };
+}
+/**
+ * チャンクを順次実行し、結果を集約する
+ *
+ * 各チャンクを独立したトランザクションとして実行し、1つのチャンクが失敗しても
+ * 他のチャンクの処理を継続する（部分成功サポート）。
+ *
+ * @param chunks - 実行するチャンク配列
+ * @param executeChunk - 各チャンクを実行する関数（成功したレコードを返す）
+ * @param getRecordId - レコードからIDを取得する関数
+ * @returns チャンク実行結果
+ *
+ * @example
+ * ```typescript
+ * const result = await executeChunks(
+ *   chunks,
+ *   async (chunk) => {
+ *     // TransactWriteItemsでチャンクを実行
+ *     await dynamoDBClient.send(new TransactWriteItemsCommand({
+ *       TransactItems: buildTransactItems(chunk)
+ *     }));
+ *     return chunk; // 成功したレコードを返す
+ *   },
+ *   (record) => record.id
+ * );
+ * ```
+ */
+export async function executeChunks(chunks, executeChunk, getRecordId) {
+    const successRecords = [];
+    const failedIds = [];
+    const errors = [];
+    const totalRecords = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const executionStartTime = Date.now();
+    logger.info('Starting chunk execution', {
+        totalChunks: chunks.length,
+        totalRecords,
+    });
+    // 各チャンクを順次実行
+    for (let i = 0; i < chunks.length; i++) {
+        const chunk = chunks[i];
+        const chunkStartTime = Date.now();
+        try {
+            logger.debug(`Executing chunk ${i + 1}/${chunks.length}`, {
+                chunkIndex: i,
+                recordCount: chunk.length,
+            });
+            // チャンクを実行
+            const successfulRecords = await executeChunk(chunk);
+            successRecords.push(...successfulRecords);
+            const chunkDuration = Date.now() - chunkStartTime;
+            logger.info(`Chunk ${i + 1}/${chunks.length} succeeded`, {
+                chunkIndex: i,
+                recordCount: chunk.length,
+                durationMs: chunkDuration,
+            });
+        }
+        catch (error) {
+            // チャンクが失敗した場合、そのチャンク内のすべてのレコードを失敗として記録
+            const chunkDuration = Date.now() - chunkStartTime;
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            const errorCode = getErrorCode(error);
+            logger.error(`Chunk ${i + 1}/${chunks.length} failed`, {
+                chunkIndex: i,
+                recordCount: chunk.length,
+                durationMs: chunkDuration,
+                error: errorMessage,
+                errorCode,
+            });
+            // チャンク内のすべてのレコードを失敗として記録
+            for (const record of chunk) {
+                const recordId = getRecordId(record);
+                failedIds.push(recordId);
+                errors.push({
+                    id: recordId,
+                    code: errorCode,
+                    message: errorMessage,
+                });
+            }
+        }
+    }
+    const totalExecutionTime = Date.now() - executionStartTime;
+    // 実行結果のサマリーをログ出力
+    logger.info('Chunk execution completed', {
+        totalChunks: chunks.length,
+        totalRecords,
+        successCount: successRecords.length,
+        failedCount: failedIds.length,
+        totalExecutionTimeMs: totalExecutionTime,
+        avgTimePerChunkMs: chunks.length > 0 ? Math.round(totalExecutionTime / chunks.length) : 0,
+    });
+    // 部分失敗の場合、詳細なエラー情報をログ出力
+    if (failedIds.length > 0) {
+        logger.warn('Partial failure detected in chunk execution', {
+            totalRecords,
+            successCount: successRecords.length,
+            failedCount: failedIds.length,
+            failureRate: `${Math.round((failedIds.length / totalRecords) * 100)}%`,
+            failedIds: failedIds.slice(0, 10), // 最初の10件のみログ出力
+            errorSummary: errors.slice(0, 5).map((e) => ({
+                id: e.id,
+                code: e.code,
+                message: e.message.substring(0, 100), // メッセージを100文字に制限
+            })),
+        });
+    }
+    return {
+        successRecords,
+        failedIds,
+        errors,
+    };
+}
+/**
+ * エラーからエラーコードを抽出する
+ *
+ * @param error - エラーオブジェクト
+ * @returns エラーコード
+ */
+function getErrorCode(error) {
+    if (error && typeof error === 'object') {
+        // AWS SDK エラー
+        if ('name' in error && typeof error.name === 'string') {
+            return error.name;
+        }
+        // カスタムエラー
+        if ('code' in error && typeof error.code === 'string') {
+            return error.code;
+        }
+    }
+    return 'TRANSACTION_FAILED';
+}
+//# sourceMappingURL=chunking.js.map

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

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

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

@@ -0,0 +1,41 @@
+/**
+ * DynamoDB操作ユーティリティ
+ */
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+/**
+ * DynamoDBクライアントを取得する（シングルトン）
+ *
+ * @returns DynamoDBDocumentClient
+ */
+export declare function getDBClient(): DynamoDBDocumentClient;
+/**
+ * 環境変数からテーブル名を取得する
+ *
+ * @returns DynamoDBテーブル名
+ * @throws {ConfigError} TABLE_NAME環境変数が未設定の場合
+ */
+export declare function getTableName(): string;
+/**
+ * レコードから__shadowKeysを除外する
+ *
+ * @param record - DynamoDBレコード
+ * @returns __shadowKeysを除外したレコード
+ */
+export declare function removeShadowKeys(record: Record<string, unknown>): Record<string, unknown>;
+/**
+ * data属性からレコードを抽出し、__shadowKeysを除外する
+ *
+ * @param item - DynamoDBアイテム（PK, SK, data構造）
+ * @returns クリーンなレコード
+ */
+export declare function extractCleanRecord(item: Record<string, unknown>): Record<string, unknown>;
+/**
+ * DynamoDB操作を実行し、権限不足エラーを適切にハンドリングする
+ *
+ * @param operation - 実行するDynamoDB操作
+ * @param operationName - 操作名（ログ用）
+ * @returns 操作結果
+ * @throws {Error} 権限不足エラーまたはその他のエラー
+ */
+export declare function executeDynamoDBOperation<T>(operation: () => Promise<T>, operationName: string): Promise<T>;
+//# sourceMappingURL=dynamodb.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb.d.ts","sourceRoot":"","sources":["../../../src/server/utils/dynamodb.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAYpE;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,sBAAsB,CAOpD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAQrC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzF;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,CAAC,CAmBZ"}

package/dist/server/utils/dynamodb.js

@@ -0,0 +1,83 @@
+import { ConfigError, createDynamoDBClient, createLogger } from '../../index.js';
+// ロガーインスタンス
+const logger = createLogger({ service: 'records-lambda' });
+/**
+ * DynamoDBクライアントのシングルトンインスタンス
+ */
+let dbClient = null;
+/**
+ * DynamoDBクライアントを取得する（シングルトン）
+ *
+ * @returns DynamoDBDocumentClient
+ */
+export function getDBClient() {
+    if (!dbClient) {
+        dbClient = createDynamoDBClient({
+            region: process.env.AWS_REGION || process.env.REGION,
+        });
+    }
+    return dbClient;
+}
+/**
+ * 環境変数からテーブル名を取得する
+ *
+ * @returns DynamoDBテーブル名
+ * @throws {ConfigError} TABLE_NAME環境変数が未設定の場合
+ */
+export function getTableName() {
+    const tableName = process.env.TABLE_NAME;
+    if (!tableName) {
+        throw new ConfigError('TABLE_NAME environment variable is not set');
+    }
+    return tableName;
+}
+/**
+ * レコードから__shadowKeysを除外する
+ *
+ * @param record - DynamoDBレコード
+ * @returns __shadowKeysを除外したレコード
+ */
+export function removeShadowKeys(record) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { __shadowKeys, ...rest } = record;
+    return rest;
+}
+/**
+ * data属性からレコードを抽出し、__shadowKeysを除外する
+ *
+ * @param item - DynamoDBアイテム（PK, SK, data構造）
+ * @returns クリーンなレコード
+ */
+export function extractCleanRecord(item) {
+    const data = item.data;
+    return removeShadowKeys(data);
+}
+/**
+ * DynamoDB操作を実行し、権限不足エラーを適切にハンドリングする
+ *
+ * @param operation - 実行するDynamoDB操作
+ * @param operationName - 操作名（ログ用）
+ * @returns 操作結果
+ * @throws {Error} 権限不足エラーまたはその他のエラー
+ */
+export async function executeDynamoDBOperation(operation, operationName) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        // 権限不足エラーの場合、詳細なログを出力
+        if (error instanceof Error && error.name === 'AccessDeniedException') {
+            logger.error('DynamoDB access denied', {
+                errorName: error.name,
+                errorMessage: error.message,
+                operation: operationName,
+                tableName: process.env.TABLE_NAME,
+                region: process.env.AWS_REGION || process.env.REGION,
+            });
+            throw new Error(`Insufficient permissions to access DynamoDB: ${operationName}`);
+        }
+        // その他のエラーはそのまま再スロー
+        throw error;
+    }
+}
+//# sourceMappingURL=dynamodb.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dynamodb.js","sourceRoot":"","sources":["../../../src/server/utils/dynamodb.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEjF,YAAY;AACZ,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAE3D;;GAEG;AACH,IAAI,QAAQ,GAAkC,IAAI,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,QAAQ,GAAG,oBAAoB,CAAC;YAC9B,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM;SACrD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC;IAEzC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC,4CAA4C,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAA+B;IAC9D,6DAA6D;IAC7D,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IACzC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAA6B;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,IAA+B,CAAC;IAClD,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,SAA2B,EAC3B,aAAqB;IAErB,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,sBAAsB;QACtB,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,uBAAuB,EAAE,CAAC;YACrE,MAAM,CAAC,KAAK,CAAC,wBAAwB,EAAE;gBACrC,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,YAAY,EAAE,KAAK,CAAC,OAAO;gBAC3B,SAAS,EAAE,aAAa;gBACxB,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU;gBACjC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM;aACrD,CAAC,CAAC;YACH,MAAM,IAAI,KAAK,CAAC,gDAAgD,aAAa,EAAE,CAAC,CAAC;QACnF,CAAC;QAED,mBAAmB;QACnB,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,152 @@
+/**
+ * DynamoDB フィルター式生成ユーティリティ
+ * FilterExpression の構築とシャドーレコード除外条件の生成
+ *
+ * 要件: 5.5, 7.1, 12.1-12.12
+ */
+/**
+ * フィルター演算子
+ *
+ * 要件: 12.2
+ */
+export type FilterOperator = 'eq' | 'lt' | 'lte' | 'gt' | 'gte' | 'starts' | 'ends';
+/**
+ * フィルター型
+ *
+ * 要件: 12.5
+ */
+export type FilterType = 'string' | 'number' | 'date' | 'boolean';
+/**
+ * パース済みフィルターフィールド
+ *
+ * 要件: 12.1
+ */
+export interface ParsedFilterField {
+    /** 実際のフィールド名 */
+    field: string;
+    /** 演算子 */
+    operator: FilterOperator;
+    /** データ型 */
+    type: FilterType;
+}
+/**
+ * フィルター式の構築結果
+ */
+export interface FilterExpressionResult {
+    /** FilterExpression 文字列 */
+    expression: string;
+    /** ExpressionAttributeNames マッピング */
+    names: Record<string, string>;
+    /** ExpressionAttributeValues マッピング */
+    values: Record<string, unknown>;
+}
+/**
+ * フィルターフィールド名をパースする
+ *
+ * フォーマット: `フィールド名:オペレータ:型`
+ * - オペレータ省略時: eq（デフォルト）
+ * - 型省略時: string（デフォルト）
+ *
+ * 例:
+ * - "status" → { field: "status", operator: "eq", type: "string" }
+ * - "priority:gte" → { field: "priority", operator: "gte", type: "string" }
+ * - "priority:gte:number" → { field: "priority", operator: "gte", type: "number" }
+ *
+ * 要件: 12.1, 12.3, 12.4
+ *
+ * @param fieldKey - フィルターフィールド名
+ * @returns パース結果
+ * @throws Error - 構文エラーの場合
+ */
+export declare function parseFilterField(fieldKey: string): ParsedFilterField;
+/**
+ * シャドーレコードを除外するフィルター式を生成する
+ *
+ * シャドーレコードの特徴:
+ * - SK に '#' が含まれる（例: "name#value#id#ULID"）
+ * - 本体レコードは "id#ULID" 形式で '#' が1つのみ
+ *
+ * 除外条件:
+ * - attribute_exists(data) AND NOT contains(SK, '#id#')
+ *
+ * @returns シャドー除外フィルター式
+ */
+export declare function createShadowExclusionFilter(): FilterExpressionResult;
+/**
+ * ユーザー指定のフィルター条件から FilterExpression を構築する
+ *
+ * 注意: この実装は基本的な等価比較のみをサポート
+ * より複雑な条件（範囲検索、部分一致など）は将来の拡張として実装可能
+ *
+ * @param filter - フィルター条件（キー: フィールド名、値: 期待値）
+ * @returns フィルター式の構築結果
+ */
+export declare function buildFilterExpression(filter: Record<string, unknown>): FilterExpressionResult | null;
+/**
+ * 複数のフィルター式を AND 条件で結合する
+ *
+ * @param filters - 結合するフィルター式の配列
+ * @returns 結合されたフィルター式
+ */
+export declare function combineFilters(filters: (FilterExpressionResult | null)[]): FilterExpressionResult | null;
+/**
+ * フィルター式を DynamoDB Query/Scan パラメータに適用する
+ *
+ * @param params - DynamoDB Query/Scan パラメータ
+ * @param filter - フィルター式
+ * @returns フィルター式が適用されたパラメータ
+ */
+export declare function applyFilterExpression<T extends Record<string, unknown>>(params: T, filter: FilterExpressionResult | null): T;
+/**
+ * 型変換ヘルパー
+ *
+ * 要件: 12.5
+ *
+ * @param value - 変換する値
+ * @param type - 変換先の型
+ * @returns 変換後の値
+ */
+export declare function convertType(value: unknown, type: FilterType): string | number | Date | boolean;
+/**
+ * レコードが単一のフィルター条件に一致するかチェックする
+ *
+ * 要件: 12.2, 12.6, 12.8, 12.9
+ *
+ * @param record - チェック対象レコード
+ * @param parsed - パース済みフィルター条件
+ * @param value - フィルター値
+ * @returns 一致する場合true
+ */
+export declare function matchesFilter(record: Record<string, unknown>, parsed: ParsedFilterField, value: unknown): boolean;
+/**
+ * レコードがすべてのフィルター条件に一致するかチェックする（AND条件）
+ *
+ * 要件: 12.9
+ *
+ * @param record - チェック対象レコード
+ * @param parsedFilters - パース済みフィルター条件の配列
+ * @returns すべての条件に一致する場合true
+ */
+export declare function matchesAllFilters(record: Record<string, unknown>, parsedFilters: Array<{
+    parsed: ParsedFilterField;
+    value: unknown;
+}>): boolean;
+/**
+ * Query最適化が可能かチェックする
+ *
+ * ソートフィールドと一致し、Query可能な演算子を持つフィルター条件を検出する
+ *
+ * 要件: 12.7
+ *
+ * @param sortField - ソート対象フィールド
+ * @param parsedFilters - パース済みフィルター条件
+ * @returns 最適化可能なフィルター条件（なければnull）
+ */
+export declare function findOptimizableFilter(sortField: string, parsedFilters: Array<{
+    parsed: ParsedFilterField;
+    value: unknown;
+}>): {
+    parsed: ParsedFilterField;
+    value: unknown;
+} | null;
+//# sourceMappingURL=filter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../../src/server/utils/filter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEpF;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU;IACV,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW;IACX,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAiCpE;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,sBAAsB,CAWpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,sBAAsB,GAAG,IAAI,CA4B/B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,CAAC,sBAAsB,GAAG,IAAI,CAAC,EAAE,GACzC,sBAAsB,GAAG,IAAI,CA6B/B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrE,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,sBAAsB,GAAG,IAAI,GACpC,CAAC,CAiBH;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,CAe9F;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,OAAO,GACb,OAAO,CA+BT;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,aAAa,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,GAClE,OAAO,CAET;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,GAClE;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAUtD"}