メインコンテンツまでスキップ

インターフェース

このドキュメントでは、MBC CQRS Serverlessフレームワークで使用されるすべてのTypeScriptインターフェースの包括的なリファレンスを提供します。

コアインターフェース​

コマンドインターフェース​

CommandInputModel​

新しいコマンドを作成するためのプライマリインターフェース。新しいエンティティを発行する際に使用します。

export interface CommandInputModel {
  pk: string              // Partition key (e.g., "ORDER#tenant001")
  sk: string              // Sort key with version (e.g., "ORDER#ORD001#v0")
  id: string              // Unique identifier (e.g., UUID)
  code: string            // Business code (e.g., "ORD001")
  name: string            // Display name
  version: number         // Version number for optimistic locking
  tenantCode: string      // Tenant identifier
  type: string            // Entity type (e.g., "ORDER")
  isDeleted?: boolean     // Soft delete flag
  seq?: number            // Sequence number (auto-generated)
  ttl?: number            // Time-to-live timestamp (Unix epoch)
  attributes?: Record<string, any>  // Custom domain attributes
}

使用例:

const orderInput: CommandInputModel = {
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001#v0',
  id: crypto.randomUUID(),
  code: 'ORD001',
  name: 'Customer Order',
  version: 1,
  tenantCode: 'tenant001',
  type: 'ORDER',
  attributes: {
    customerId: 'CUST001',
    totalAmount: 1500,
    status: 'pending',
  },
};

CommandPartialInputModel​

部分更新に使用します。pk、sk、versionのみが必須です。

export interface CommandPartialInputModel extends Partial<CommandInputModel> {
  pk: string       // Required: Partition key
  sk: string       // Required: Sort key
  version: number  // Required: Current version for optimistic locking
}

使用例:

const partialUpdate: CommandPartialInputModel = {
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',
  version: 2,  // Must match current version
  name: 'Updated Order Name',
  attributes: {
    status: 'confirmed',
  },
};

ICommandOptions​

コマンド発行メソッドに渡されるオプション。

export interface ICommandOptions {
  source?: string        // Source identifier for tracking
  requestId?: string     // Request ID for tracing
  invokeContext: IInvoke // Required: Invocation context
}

使用例:

const options: ICommandOptions = {
  source: 'order-service',
  requestId: context.awsRequestId,
  invokeContext: {
    userContext: getUserContext(event),
    tenantCode: 'tenant001',
  },
};

キーインターフェース​

DetailKey​

DynamoDBアイテムのプライマリキーを表します。

export interface DetailKey {
  pk: string  // Partition key
  sk: string  // Sort key
}

コンテキストインターフェース​

IInvoke​

Lambda/Expressのイベントとコンテキストを含む呼び出しコンテキスト。

export interface IInvoke {
  event?: IInvokeEvent      // Request event (headers, requestContext等のリクエストイベント)
  context?: IInvokeContext  // Lambda context (requestId, functionName等のLambdaコンテキスト)
}

IInvokeEvent​

API GatewayまたはExpressからのHTTPリクエストイベント構造。

export interface IInvokeEvent {
  version?: string
  routeKey?: string                    // e.g., "POST /api/resource" (例: "POST /api/resource")
  rawPath?: string
  rawQueryString?: string
  headers?: Record<string, string>
  requestContext?: {
    accountId?: string
    apiId?: string
    domainName?: string
    domainPrefix?: string
    http?: {
      method?: string
      path?: string
      protocol?: string
      sourceIp?: string                // Client IP address (クライアントIPアドレス)
      userAgent?: string
    }
    requestId?: string
    stage?: string
    time?: string
    timeEpoch?: number
    authorizer?: {
      jwt?: {
        claims?: JwtClaims             // Decoded JWT claims (デコードされたJWTクレーム)
        scopes?: string[]
      }
    }
  }
  isBase64Encoded?: boolean
}

IInvokeContext​

Lambda実行コンテキスト情報。

export interface IInvokeContext {
  functionName?: string               // Lambda function name (Lambda関数名)
  functionVersion?: string            // Lambda function version (Lambda関数バージョン)
  invokedFunctionArn?: string         // Lambda ARN (Lambda ARN)
  memoryLimitInMB?: string           // Memory limit (メモリ制限)
  awsRequestId?: string              // AWS request ID for tracing (トレース用AWSリクエストID)
  logGroupName?: string              // CloudWatch log group (CloudWatchロググループ)
  logStreamName?: string             // CloudWatch log stream (CloudWatchログストリーム)
  identity?: {
    cognitoIdentityId?: string
    cognitoIdentityPoolId?: string
  }
}

JwtClaims​

CognitoからのJWTトークンクレーム構造。

export interface JwtClaims {
  sub: string                        // Cognito user ID (UUID) (CognitoユーザーID)
  iss: string                        // Token issuer URL (トークン発行者URL)
  username?: string
  'cognito:groups'?: string[]        // Cognito groups the user belongs to (ユーザーが所属するCognitoグループ)
  'cognito:username': string         // Cognito username (Cognitoユーザー名)
  origin_jti?: string                // Original JWT ID (元のJWT ID)
  client_id?: string                 // OAuth client ID (OAuthクライアントID)
  scope?: string                     // OAuth scopes (OAuthスコープ)
  aud: string                        // Audience (client ID) (オーディエンス/クライアントID)
  event_id: string
  token_use: string                  // Token type (id or access) (トークンタイプ: id または access)
  auth_time: number                  // Authentication timestamp (認証タイムスタンプ)
  name: string                       // User's display name (ユーザー表示名)
  'custom:tenant'?: string           // Custom claim for tenant code (テナントコード用カスタムクレーム)
  'custom:roles'?: string            // Custom claim for roles JSON array (ロールJSON配列用カスタムクレーム)
  exp: number                        // Token expiration timestamp (トークン有効期限タイムスタンプ)
  email: string
  email_verified?: boolean
  iat: number                        // Token issued at timestamp (トークン発行タイムスタンプ)
  jti: string                        // JWT ID (JWT ID)
}

カスタムクレームの例:

// The custom:roles claim contains a JSON array of role assignments (custom:rolesクレームはロール割り当てのJSON配列を含む)
// [{"tenant":"","role":"user"},{"tenant":"9999","role":"admin"}]
// - Empty tenant ("") means the role applies globally (空のテナント("")はロールがグローバルに適用されることを意味する)
// - Specific tenant means the role applies only to that tenant (特定のテナントはロールがそのテナントのみに適用されることを意味する)

UserContext​

認証トークンから抽出されるユーザーコンテキストクラス。

export class UserContext {
  userId: string      // Cognito user ID (from JWT sub claim)
  tenantRole: string  // User's role within the tenant
  tenantCode: string  // Current tenant code

  constructor(partial: Partial<UserContext>)  // Initialize with partial properties (部分的なプロパティで初期化)
}

使用例:

import { getUserContext, IInvoke } from '@mbc-cqrs-serverless/core';

// Extract user context from IInvoke or ExecutionContext
const userContext = getUserContext(invokeContext);
console.log(userContext.userId);      // '92ca4f68-9ac6-4080-9ae2-2f02a86206a4'
console.log(userContext.tenantCode);  // 'tenant001'
console.log(userContext.tenantRole);  // 'admin'

データインターフェース​

エンティティインターフェース​

CommandModel​

コマンドエンティティ（書き込みモデル）のインターフェース。

export interface CommandModel extends CommandInputModel {
  status?: string       // Processing status (処理ステータス: 'PENDING', 'COMPLETED', 'FAILED'等)
  source?: string       // Event source identifier (イベントソース識別子: 'POST /api/master', 'SQS'等)
  requestId?: string    // Unique request ID for tracing and idempotency (トレースと冪等性のための一意のリクエストID)
  createdAt?: Date      // Timestamp when the command was created (コマンド作成時のタイムスタンプ)
  updatedAt?: Date      // Timestamp when the command was last updated (コマンド最終更新時のタイムスタンプ)
  createdBy?: string    // User ID who created the command (コマンドを作成したユーザーID)
  updatedBy?: string    // User ID who last updated the command (コマンドを最後に更新したユーザーID)
  createdIp?: string    // IP address of the creator (作成者のIPアドレス)
  updatedIp?: string    // IP address of the last updater (最終更新者のIPアドレス)
  taskToken?: string    // Step Functions task token for async workflows (非同期ワークフロー用のStep Functionsタスクトークン)
}
Step Functions連携

taskTokenフィールドは、AWS Step Functionsコールバックパターンと統合する際に使用されます。Step Functionsステートマシンがタスクトークンでアプリケーションを呼び出す場合、CommandService.updateTaskToken()を使用してトークンを保存します。その後、AWS SDKのSendTaskSuccessCommandまたはSendTaskFailureCommandでトークンを使用してタスク完了を通知します。

DataModel​

データエンティティ（読み取りモデル）の基本インターフェース。

export interface DataModel extends Omit<CommandModel, 'status'> {
  cpk?: string  // Command partition key - references source command record (コマンドパーティションキー - ソースコマンドレコードへの参照)
  csk?: string  // Command sort key with version - references exact command version (バージョン付きコマンドソートキー - 正確なコマンドバージョンへの参照)
}

エンティティクラス​

CommandEntity​

APIレスポンス用にCommandModelを実装したクラス。Swaggerデコレータを含みます。

export class CommandEntity implements CommandModel {
  // All properties from CommandModel (CommandModelのすべてのプロパティ)
  pk: string
  sk: string
  // ...

  get key(): DetailKey  // Returns { pk, sk } for DynamoDB operations (DynamoDB操作用の { pk, sk } を返す)
}

使用例:

const command: CommandEntity = await commandService.findOne({
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',
});

// Access the DynamoDB key pair (DynamoDBキーペアにアクセス)
const key = command.key;  // { pk: 'ORDER#tenant001', sk: 'ORDER#ORD001' }

DataEntity​

APIレスポンス用にDataModelを実装したクラス。Swaggerデコレータを含みます。

export class DataEntity implements DataModel {
  // All properties from DataModel (DataModelのすべてのプロパティ)
  pk: string
  sk: string
  // ...

  constructor(data: Partial<DataEntity>)  // Initialize with partial properties (部分的なプロパティで初期化)

  get key(): DetailKey  // Returns { pk, sk } for DynamoDB operations (DynamoDB操作用の { pk, sk } を返す)
}

使用例:

const data: DataEntity = await dataService.findOne({
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',
});

// Access the DynamoDB key pair (DynamoDBキーペアにアクセス)
const key = data.key;  // { pk: 'ORDER#tenant001', sk: 'ORDER#ORD001' }

リストレスポンスインターフェース​

DataListEntity​

データクエリ用のページネーション付きリストレスポンス。

export class DataListEntity {
  items: DataEntity[]   // Array of entities
  total?: number        // Total count (if available)
  lastSk?: string       // Pagination cursor (last sort key)

  constructor(data: Partial<DataListEntity>)  // Initialize with partial properties (部分的なプロパティで初期化)
}

使用例:

const result = await dataService.listItemsByPk('ORDER#tenant001', {
  limit: 20,
  startFromSk: previousLastSk,
});

// Pagination
if (result.lastSk) {
  // More items available - use result.lastSk for next page
}

サービスインターフェース​

同期ハンドラーインターフェース​

IDataSyncHandler​

データ同期ハンドラーを実装するためのインターフェース。前進（up）およびロールバック（down）操作の両方を処理します。

export interface IDataSyncHandler<TExecuteResult = any, TRollbackResult = any> {
  readonly type?: string  // Optional type identifier

  /**
   * Sync data when a command is executed.
   * Called automatically by the framework during command processing.
   */
  up(cmd: CommandModel): Promise<TExecuteResult>

  /**
   * Reserved for rollback operations.
   * Note: This method is NOT automatically called by the framework.
   * Implement this for manual rollback scenarios in your application.
   */
  down(cmd: CommandModel): Promise<TRollbackResult>
}

実装例:

@Injectable()
export class OrderRdsSyncHandler implements IDataSyncHandler {
  readonly type = 'ORDER';

  constructor(private readonly prisma: PrismaService) {}

  async up(cmd: CommandModel): Promise<void> {
    if (cmd.isDeleted) {
      await this.prisma.order.delete({
        where: { id: cmd.id },
      });
    } else {
      await this.prisma.order.upsert({
        where: { id: cmd.id },
        create: this.toRdsModel(cmd),
        update: this.toRdsModel(cmd),
      });
    }
  }

  async down(cmd: CommandModel): Promise<void> {
    // Rollback logic - restore previous state
    await this.prisma.order.delete({
      where: { id: cmd.id },
    });
  }

  private toRdsModel(cmd: CommandModel) {
    return {
      id: cmd.id,
      code: cmd.code,
      name: cmd.name,
      ...cmd.attributes,
    };
  }
}

通知インターフェース​

EmailNotification​

メール通知送信用の設定。

export interface EmailNotification {
  fromAddr?: string       // Sender address (uses default if not specified)
  toAddrs: string[]       // Required: Recipient addresses
  ccAddrs?: string[]      // CC addresses
  bccAddrs?: string[]     // BCC addresses
  subject: string         // Required: Email subject
  body: string            // Required: HTML body content
  replyToAddrs?: string[] // Reply-to addresses
  attachments?: Attachment[]  // File attachments
}

export interface Attachment {
  filename: string      // Attachment filename
  content: Buffer       // File content as Buffer
  contentType?: string  // MIME type (e.g., 'application/pdf')
}

使用例:

await emailService.sendEmail({
  toAddrs: ['user@example.com'],
  subject: 'Order Confirmation',
  body: `<h1>Order Confirmed</h1><p>Your order ${orderCode} has been confirmed.</p>`,
});

モジュール設定インターフェース​

CommandModuleOptions​

CommandModuleの設定オプション。

export interface CommandModuleOptions {
  tableName: string                           // DynamoDB table name
  dataSyncHandlers?: Type<IDataSyncHandler>[] // Custom sync handlers
  skipError?: boolean                         // Reserved for future use (not yet implemented)
  disableDefaultHandler?: boolean             // Disable the default DynamoDB data sync handler
}

使用例:

@Module({
  imports: [
    CommandModule.register({
      tableName: 'order',
      dataSyncHandlers: [OrderRdsSyncHandler],
      disableDefaultHandler: false,
    }),
  ],
})
export class OrderModule {}

SequencesModuleOptions​

SequenceModuleの設定オプション。

export interface SequencesModuleOptions {
  enableController?: boolean  // Enable or disable default sequence controller
}

イベントインターフェース​

StepFunctionsEvent​

AWS Step Functionsからのイベント構造。

export interface StepFunctionsContextExecution {
  Id: string                    // Execution ID (実行ID)
  Input: { [id: string]: any }  // Input data (入力データ)
  Name: string                  // Execution name (実行名)
  RoleArn: string               // IAM role ARN (IAMロールARN)
  StartTime: string             // Execution start time (実行開始時刻)
}

export interface StepFunctionsContextState {
  EnteredTime: string   // State entered time (ステート開始時刻)
  Name: string          // State name (ステート名)
  RetryCount: number    // Retry count (リトライ回数)
}

export interface StepFunctionsContextStateMachine {
  Id: string    // State machine ID (ステートマシンID)
  Name: string  // State machine name (ステートマシン名)
}

export interface StepFunctionsContext {
  Execution: StepFunctionsContextExecution
  State: StepFunctionsContextState
  StateMachine: StepFunctionsContextStateMachine
}

export interface StepFunctionsEvent<TInput> {
  input: TInput                    // Input data passed to the state (ステートに渡された入力データ)
  context: StepFunctionsContext    // Step Functions context information (Step Functionsコンテキスト情報)
}

型ユーティリティ​

共通型ヘルパー​

// Partial type that requires specific keys
type RequiredPick<T, K extends keyof T> = Partial<T> & Pick<T, K>;

// Deep partial type
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// Entity without audit fields
type EntityInput<T> = Omit<T, 'createdAt' | 'createdBy' | 'updatedAt' | 'updatedBy'>;

関連情報​