Command Handler

Description

Processes a specific type of Command, orchestrating domain objects to fulfill the command's intent.

Definition Schema

The definition for a command_handler component expects the following structure:

{
  "$defs": {
    "CommandHandlerDependencyInputDTO": {
      "example": {
        "assigned_attribute_name": "_sessionmaker",
        "param_name": "session",
        "param_type_str": "sessionmaker[Session]"
      },
      "example_with_explicit_import": {
        "param_import_from_module": "sqlalchemy.ext.asyncio",
        "param_import_names": [
          "AsyncSession"
        ],
        "param_name": "async_session_factory",
        "param_type_str": "AsyncSession"
      },
      "properties": {
        "param_name": {
          "description": "Name of the parameter in __init__ (e.g., 'post_aggregate_repository')",
          "title": "Param Name",
          "type": "string"
        },
        "param_type_str": {
          "description": "Type hint string for the parameter (e.g., 'AggregateRepository[uuid.UUID, PostAggregate, Post]')",
          "title": "Param Type Str",
          "type": "string"
        },
        "assigned_attribute_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Name of the attribute to assign the dependency to on self (e.g., '_repository'). Defaults to '_' + param_name if None.",
          "title": "Assigned Attribute Name"
        },
        "param_import_from_module": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional: Explicit module to import the dependency type from (e.g., 'sqlalchemy.ext.asyncio').",
          "title": "Param Import From Module"
        },
        "param_import_names": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Optional: Explicit list of names to import from the module (e.g., ['AsyncSession']). Used if param_import_from_module is set.",
          "title": "Param Import Names"
        }
      },
      "required": [
        "param_name",
        "param_type_str"
      ],
      "title": "CommandHandlerDependencyInputDTO",
      "type": "object"
    },
    "PermissionDefinitionForCtxDTO": {
      "example": {
        "action": "ActionEnum.CREATE",
        "resource": "ResourceEnum.ITEM",
        "scope": "ScopeEnum.GENERAL"
      },
      "properties": {
        "action": {
          "description": "Action string, e.g., 'RevisionDraftExpertAction.CREATE' or 'module.action_enum.ACTION'",
          "title": "Action",
          "type": "string"
        },
        "resource": {
          "description": "Resource string, e.g., 'RevisionDraftResource.REVISION_DRAFT' or 'module.resource_enum.RESOURCE'",
          "title": "Resource",
          "type": "string"
        },
        "scope": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "description": "Scope string, e.g., 'RevisionDraftLifecycleScope.ANY_STATUS' or 'module.scope_enum.SCOPE'",
          "title": "Scope"
        }
      },
      "required": [
        "action",
        "resource"
      ],
      "title": "PermissionDefinitionForCtxDTO",
      "type": "object"
    }
  },
  "example": {
    "command_bus_instance_name": "command_bus",
    "command_module": "app_root_name.application.posts.commands.create_post_command",
    "command_name": "CreatePostCommand",
    "dependencies": [
      {
        "assigned_attribute_name": "_sessionmaker",
        "param_name": "session",
        "param_type_str": "sessionmaker[Session]"
      },
      {
        "assigned_attribute_name": "_repository",
        "param_name": "post_aggregate_repository",
        "param_type_str": "AggregateRepository[uuid.UUID, PostAggregate, Post]"
      },
      {
        "assigned_attribute_name": "_publisher",
        "param_name": "event_publisher",
        "param_type_str": "ExternalEventPublisher"
      }
    ],
    "execute_method_ctx_permissions": [
      {
        "action": "RevisionDraftExpertAction.CREATE",
        "resource": "RevisionDraftResource.REVISION_DRAFT",
        "scope": "RevisionDraftLifecycleScope.ANY_STATUS"
      }
    ],
    "execute_return_type_str": "uuid.UUID",
    "include_basic_authorize": true,
    "name": "CreatePostCommandHandler"
  },
  "properties": {
    "name": {
      "description": "Name of the handler class (e.g., 'CreatePostCommandHandler')",
      "title": "Name",
      "type": "string"
    },
    "command_name": {
      "description": "Name of the command class it handles (e.g., 'CreatePostCommand')",
      "title": "Command Name",
      "type": "string"
    },
    "command_module": {
      "description": "Module where the command class is defined (e.g., 'app_root_name.application.posts.commands')",
      "title": "Command Module",
      "type": "string"
    },
    "dependencies": {
      "description": "List of dependencies for the __init__ method.",
      "items": {
        "$ref": "#/$defs/CommandHandlerDependencyInputDTO"
      },
      "title": "Dependencies",
      "type": "array"
    },
    "execute_return_type_str": {
      "default": "None",
      "description": "Return type hint string for the execute method (e.g., 'uuid.UUID', 'None')",
      "title": "Execute Return Type Str",
      "type": "string"
    },
    "include_basic_authorize": {
      "default": true,
      "description": "Whether to include a basic 'authorize' method returning True.",
      "title": "Include Basic Authorize",
      "type": "boolean"
    },
    "execute_method_ctx_permissions": {
      "anyOf": [
        {
          "items": {
            "$ref": "#/$defs/PermissionDefinitionForCtxDTO"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Permissions for the @ctx decorator on the execute method. Each string should be a valid Python expression for a Permission object.",
      "title": "Execute Method Ctx Permissions"
    },
    "command_bus_instance_name": {
      "default": "command_bus",
      "description": "Name of the command bus instance variable used for the @register decorator.",
      "title": "Command Bus Instance Name",
      "type": "string"
    }
  },
  "required": [
    "name",
    "command_name",
    "command_module"
  ],
  "title": "CommandHandlerInputDTO",
  "type": "object"
}

Naming and Location Conventions

Class: PascalCase, typically ends with 'CommandHandler'. File: ${command_handler_name}.py (based on ${command_handler_name}). Location: app/application/${bounded_ctx}/handlers. (Requires context: ['bounded_ctx'])

Example Definition

{
  "name": "CreatePostCommandHandler",
  "command_name": "CreatePostCommand",
  "command_module": "app_root_name.application.posts.commands.create_post_command",
  "dependencies": [
    {
      "param_name": "session",
      "param_type_str": "sessionmaker[Session]",
      "assigned_attribute_name": "_sessionmaker"
    },
    {
      "param_name": "post_aggregate_repository",
      "param_type_str": "AggregateRepository[uuid.UUID, PostAggregate, Post]",
      "assigned_attribute_name": "_repository"
    },
    {
      "param_name": "event_publisher",
      "param_type_str": "ExternalEventPublisher",
      "assigned_attribute_name": "_publisher"
    }
  ],
  "execute_return_type_str": "uuid.UUID",
  "include_basic_authorize": true,
  "execute_method_ctx_permissions": [
    {
      "action": "RevisionDraftExpertAction.CREATE",
      "resource": "RevisionDraftResource.REVISION_DRAFT",
      "scope": "RevisionDraftLifecycleScope.ANY_STATUS"
    }
  ],
  "command_bus_instance_name": "command_bus"
}